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