1 /* SPDX-License-Identifier: BSD-3-Clause */ 1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /* 2 /*
3 * Virtio Mem Device 3 * Virtio Mem Device
4 * 4 *
5 * Copyright Red Hat, Inc. 2020 5 * Copyright Red Hat, Inc. 2020
6 * 6 *
7 * Authors: 7 * Authors:
8 * David Hildenbrand <david@redhat.com> 8 * David Hildenbrand <david@redhat.com>
9 * 9 *
10 * This header is BSD licensed so anyone can u 10 * This header is BSD licensed so anyone can use the definitions
11 * to implement compatible drivers/servers: 11 * to implement compatible drivers/servers:
12 * 12 *
13 * Redistribution and use in source and binary 13 * Redistribution and use in source and binary forms, with or without
14 * modification, are permitted provided that t 14 * modification, are permitted provided that the following conditions
15 * are met: 15 * are met:
16 * 1. Redistributions of source code must reta 16 * 1. Redistributions of source code must retain the above copyright
17 * notice, this list of conditions and the 17 * notice, this list of conditions and the following disclaimer.
18 * 2. Redistributions in binary form must repr 18 * 2. Redistributions in binary form must reproduce the above copyright
19 * notice, this list of conditions and the 19 * notice, this list of conditions and the following disclaimer in the
20 * documentation and/or other materials pro 20 * documentation and/or other materials provided with the distribution.
21 * 3. Neither the name of IBM nor the names of 21 * 3. Neither the name of IBM nor the names of its contributors
22 * may be used to endorse or promote produc 22 * may be used to endorse or promote products derived from this software
23 * without specific prior written permissio 23 * without specific prior written permission.
24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRAN 25 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCH 26 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
27 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. I 27 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL IBM OR
28 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDI 28 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
29 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGE 29 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
30 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 30 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
31 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUP 31 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
32 * ON ANY THEORY OF LIABILITY, WHETHER IN CONT 32 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
33 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
34 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISE 34 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 * SUCH DAMAGE. 35 * SUCH DAMAGE.
36 */ 36 */
37 37
38 #ifndef _LINUX_VIRTIO_MEM_H 38 #ifndef _LINUX_VIRTIO_MEM_H
39 #define _LINUX_VIRTIO_MEM_H 39 #define _LINUX_VIRTIO_MEM_H
40 40
41 #include <linux/types.h> 41 #include <linux/types.h>
42 #include <linux/virtio_types.h> 42 #include <linux/virtio_types.h>
43 #include <linux/virtio_ids.h> 43 #include <linux/virtio_ids.h>
44 #include <linux/virtio_config.h> 44 #include <linux/virtio_config.h>
45 45
46 /* 46 /*
47 * Each virtio-mem device manages a dedicated 47 * Each virtio-mem device manages a dedicated region in physical address
48 * space. Each device can belong to a single N 48 * space. Each device can belong to a single NUMA node, multiple devices
49 * for a single NUMA node are possible. A virt 49 * for a single NUMA node are possible. A virtio-mem device is like a
50 * "resizable DIMM" consisting of small memory 50 * "resizable DIMM" consisting of small memory blocks that can be plugged
51 * or unplugged. The device driver is responsi 51 * or unplugged. The device driver is responsible for (un)plugging memory
52 * blocks on demand. 52 * blocks on demand.
53 * 53 *
54 * Virtio-mem devices can only operate on thei 54 * Virtio-mem devices can only operate on their assigned memory region in
55 * order to (un)plug memory. A device cannot ( 55 * order to (un)plug memory. A device cannot (un)plug memory belonging to
56 * other devices. 56 * other devices.
57 * 57 *
58 * The "region_size" corresponds to the maximu 58 * The "region_size" corresponds to the maximum amount of memory that can
59 * be provided by a device. The "size" corresp 59 * be provided by a device. The "size" corresponds to the amount of memory
60 * that is currently plugged. "requested_size" 60 * that is currently plugged. "requested_size" corresponds to a request
61 * from the device to the device driver to (un 61 * from the device to the device driver to (un)plug blocks. The
62 * device driver should try to (un)plug blocks 62 * device driver should try to (un)plug blocks in order to reach the
63 * "requested_size". It is impossible to plug 63 * "requested_size". It is impossible to plug more memory than requested.
64 * 64 *
65 * The "usable_region_size" represents the mem 65 * The "usable_region_size" represents the memory region that can actually
66 * be used to (un)plug memory. It is always at 66 * be used to (un)plug memory. It is always at least as big as the
67 * "requested_size" and will grow dynamically. 67 * "requested_size" and will grow dynamically. It will only shrink when
68 * explicitly triggered (VIRTIO_MEM_REQ_UNPLUG 68 * explicitly triggered (VIRTIO_MEM_REQ_UNPLUG).
69 * 69 *
70 * There are no guarantees what will happen if 70 * There are no guarantees what will happen if unplugged memory is
71 * read/written. In general, unplugged memory 71 * read/written. In general, unplugged memory should not be touched, because
72 * the resulting action is undefined. There is 72 * the resulting action is undefined. There is one exception: without
73 * VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE, unplug 73 * VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE, unplugged memory inside the usable
74 * region can be read, to simplify creation of 74 * region can be read, to simplify creation of memory dumps.
75 * 75 *
76 * It can happen that the device cannot proces 76 * It can happen that the device cannot process a request, because it is
77 * busy. The device driver has to retry later. 77 * busy. The device driver has to retry later.
78 * 78 *
79 * Usually, during system resets all memory wi 79 * Usually, during system resets all memory will get unplugged, so the
80 * device driver can start with a clean state. 80 * device driver can start with a clean state. However, in specific
81 * scenarios (if the device is busy) it can ha 81 * scenarios (if the device is busy) it can happen that the device still
82 * has memory plugged. The device driver can r 82 * has memory plugged. The device driver can request to unplug all memory
83 * (VIRTIO_MEM_REQ_UNPLUG) - which might take 83 * (VIRTIO_MEM_REQ_UNPLUG) - which might take a while to succeed if the
84 * device is busy. 84 * device is busy.
85 */ 85 */
86 86
87 /* --- virtio-mem: feature bits --- */ 87 /* --- virtio-mem: feature bits --- */
88 88
89 /* node_id is an ACPI PXM and is valid */ 89 /* node_id is an ACPI PXM and is valid */
90 #define VIRTIO_MEM_F_ACPI_PXM 0 90 #define VIRTIO_MEM_F_ACPI_PXM 0
91 /* unplugged memory must not be accessed */ 91 /* unplugged memory must not be accessed */
92 #define VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE 92 #define VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE 1
93 /* plugged memory will remain plugged when sus 93 /* plugged memory will remain plugged when suspending+resuming */
94 #define VIRTIO_MEM_F_PERSISTENT_SUSPEND 94 #define VIRTIO_MEM_F_PERSISTENT_SUSPEND 2
95 95
96 96
97 /* --- virtio-mem: guest -> host requests --- 97 /* --- virtio-mem: guest -> host requests --- */
98 98
99 /* request to plug memory blocks */ 99 /* request to plug memory blocks */
100 #define VIRTIO_MEM_REQ_PLUG 100 #define VIRTIO_MEM_REQ_PLUG 0
101 /* request to unplug memory blocks */ 101 /* request to unplug memory blocks */
102 #define VIRTIO_MEM_REQ_UNPLUG 102 #define VIRTIO_MEM_REQ_UNPLUG 1
103 /* request to unplug all blocks and shrink the 103 /* request to unplug all blocks and shrink the usable size */
104 #define VIRTIO_MEM_REQ_UNPLUG_ALL 104 #define VIRTIO_MEM_REQ_UNPLUG_ALL 2
105 /* request information about the plugged state 105 /* request information about the plugged state of memory blocks */
106 #define VIRTIO_MEM_REQ_STATE 106 #define VIRTIO_MEM_REQ_STATE 3
107 107
108 struct virtio_mem_req_plug { 108 struct virtio_mem_req_plug {
109 __virtio64 addr; 109 __virtio64 addr;
110 __virtio16 nb_blocks; 110 __virtio16 nb_blocks;
111 __virtio16 padding[3]; 111 __virtio16 padding[3];
112 }; 112 };
113 113
114 struct virtio_mem_req_unplug { 114 struct virtio_mem_req_unplug {
115 __virtio64 addr; 115 __virtio64 addr;
116 __virtio16 nb_blocks; 116 __virtio16 nb_blocks;
117 __virtio16 padding[3]; 117 __virtio16 padding[3];
118 }; 118 };
119 119
120 struct virtio_mem_req_state { 120 struct virtio_mem_req_state {
121 __virtio64 addr; 121 __virtio64 addr;
122 __virtio16 nb_blocks; 122 __virtio16 nb_blocks;
123 __virtio16 padding[3]; 123 __virtio16 padding[3];
124 }; 124 };
125 125
126 struct virtio_mem_req { 126 struct virtio_mem_req {
127 __virtio16 type; 127 __virtio16 type;
128 __virtio16 padding[3]; 128 __virtio16 padding[3];
129 129
130 union { 130 union {
131 struct virtio_mem_req_plug plu 131 struct virtio_mem_req_plug plug;
132 struct virtio_mem_req_unplug u 132 struct virtio_mem_req_unplug unplug;
133 struct virtio_mem_req_state st 133 struct virtio_mem_req_state state;
134 } u; 134 } u;
135 }; 135 };
136 136
137 137
138 /* --- virtio-mem: host -> guest response --- 138 /* --- virtio-mem: host -> guest response --- */
139 139
140 /* 140 /*
141 * Request processed successfully, applicable 141 * Request processed successfully, applicable for
142 * - VIRTIO_MEM_REQ_PLUG 142 * - VIRTIO_MEM_REQ_PLUG
143 * - VIRTIO_MEM_REQ_UNPLUG 143 * - VIRTIO_MEM_REQ_UNPLUG
144 * - VIRTIO_MEM_REQ_UNPLUG_ALL 144 * - VIRTIO_MEM_REQ_UNPLUG_ALL
145 * - VIRTIO_MEM_REQ_STATE 145 * - VIRTIO_MEM_REQ_STATE
146 */ 146 */
147 #define VIRTIO_MEM_RESP_ACK 147 #define VIRTIO_MEM_RESP_ACK 0
148 /* 148 /*
149 * Request denied - e.g. trying to plug more t 149 * Request denied - e.g. trying to plug more than requested, applicable for
150 * - VIRTIO_MEM_REQ_PLUG 150 * - VIRTIO_MEM_REQ_PLUG
151 */ 151 */
152 #define VIRTIO_MEM_RESP_NACK 152 #define VIRTIO_MEM_RESP_NACK 1
153 /* 153 /*
154 * Request cannot be processed right now, try 154 * Request cannot be processed right now, try again later, applicable for
155 * - VIRTIO_MEM_REQ_PLUG 155 * - VIRTIO_MEM_REQ_PLUG
156 * - VIRTIO_MEM_REQ_UNPLUG 156 * - VIRTIO_MEM_REQ_UNPLUG
157 * - VIRTIO_MEM_REQ_UNPLUG_ALL 157 * - VIRTIO_MEM_REQ_UNPLUG_ALL
158 */ 158 */
159 #define VIRTIO_MEM_RESP_BUSY 159 #define VIRTIO_MEM_RESP_BUSY 2
160 /* 160 /*
161 * Error in request (e.g. addresses/alignment) 161 * Error in request (e.g. addresses/alignment), applicable for
162 * - VIRTIO_MEM_REQ_PLUG 162 * - VIRTIO_MEM_REQ_PLUG
163 * - VIRTIO_MEM_REQ_UNPLUG 163 * - VIRTIO_MEM_REQ_UNPLUG
164 * - VIRTIO_MEM_REQ_STATE 164 * - VIRTIO_MEM_REQ_STATE
165 */ 165 */
166 #define VIRTIO_MEM_RESP_ERROR 166 #define VIRTIO_MEM_RESP_ERROR 3
167 167
168 168
169 /* State of memory blocks is "plugged" */ 169 /* State of memory blocks is "plugged" */
170 #define VIRTIO_MEM_STATE_PLUGGED 170 #define VIRTIO_MEM_STATE_PLUGGED 0
171 /* State of memory blocks is "unplugged" */ 171 /* State of memory blocks is "unplugged" */
172 #define VIRTIO_MEM_STATE_UNPLUGGED 172 #define VIRTIO_MEM_STATE_UNPLUGGED 1
173 /* State of memory blocks is "mixed" */ 173 /* State of memory blocks is "mixed" */
174 #define VIRTIO_MEM_STATE_MIXED 174 #define VIRTIO_MEM_STATE_MIXED 2
175 175
176 struct virtio_mem_resp_state { 176 struct virtio_mem_resp_state {
177 __virtio16 state; 177 __virtio16 state;
178 }; 178 };
179 179
180 struct virtio_mem_resp { 180 struct virtio_mem_resp {
181 __virtio16 type; 181 __virtio16 type;
182 __virtio16 padding[3]; 182 __virtio16 padding[3];
183 183
184 union { 184 union {
185 struct virtio_mem_resp_state s 185 struct virtio_mem_resp_state state;
186 } u; 186 } u;
187 }; 187 };
188 188
189 /* --- virtio-mem: configuration --- */ 189 /* --- virtio-mem: configuration --- */
190 190
191 struct virtio_mem_config { 191 struct virtio_mem_config {
192 /* Block size and alignment. Cannot ch 192 /* Block size and alignment. Cannot change. */
193 __le64 block_size; 193 __le64 block_size;
194 /* Valid with VIRTIO_MEM_F_ACPI_PXM. C 194 /* Valid with VIRTIO_MEM_F_ACPI_PXM. Cannot change. */
195 __le16 node_id; 195 __le16 node_id;
196 __u8 padding[6]; 196 __u8 padding[6];
197 /* Start address of the memory region. 197 /* Start address of the memory region. Cannot change. */
198 __le64 addr; 198 __le64 addr;
199 /* Region size (maximum). Cannot chang 199 /* Region size (maximum). Cannot change. */
200 __le64 region_size; 200 __le64 region_size;
201 /* 201 /*
202 * Currently usable region size. Can g 202 * Currently usable region size. Can grow up to region_size. Can
203 * shrink due to VIRTIO_MEM_REQ_UNPLUG 203 * shrink due to VIRTIO_MEM_REQ_UNPLUG_ALL (in which case no config
204 * update will be sent). 204 * update will be sent).
205 */ 205 */
206 __le64 usable_region_size; 206 __le64 usable_region_size;
207 /* 207 /*
208 * Currently used size. Changes due to 208 * Currently used size. Changes due to plug/unplug requests, but no
209 * config updates will be sent. 209 * config updates will be sent.
210 */ 210 */
211 __le64 plugged_size; 211 __le64 plugged_size;
212 /* Requested size. New plug requests c 212 /* Requested size. New plug requests cannot exceed it. Can change. */
213 __le64 requested_size; 213 __le64 requested_size;
214 }; 214 };
215 215
216 #endif /* _LINUX_VIRTIO_MEM_H */ 216 #endif /* _LINUX_VIRTIO_MEM_H */
217 217
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.