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 | |
94 | |
95 | /* --- virtio-mem: guest -> host requests --- */ |
96 | |
97 | /* request to plug memory blocks */ |
98 | #define VIRTIO_MEM_REQ_PLUG 0 |
99 | /* request to unplug memory blocks */ |
100 | #define VIRTIO_MEM_REQ_UNPLUG 1 |
101 | /* request to unplug all blocks and shrink the usable size */ |
102 | #define VIRTIO_MEM_REQ_UNPLUG_ALL 2 |
103 | /* request information about the plugged state of memory blocks */ |
104 | #define VIRTIO_MEM_REQ_STATE 3 |
105 | |
106 | struct virtio_mem_req_plug { |
107 | __virtio64 addr; |
108 | __virtio16 nb_blocks; |
109 | __virtio16 padding[3]; |
110 | }; |
111 | |
112 | struct virtio_mem_req_unplug { |
113 | __virtio64 addr; |
114 | __virtio16 nb_blocks; |
115 | __virtio16 padding[3]; |
116 | }; |
117 | |
118 | struct virtio_mem_req_state { |
119 | __virtio64 addr; |
120 | __virtio16 nb_blocks; |
121 | __virtio16 padding[3]; |
122 | }; |
123 | |
124 | struct virtio_mem_req { |
125 | __virtio16 type; |
126 | __virtio16 padding[3]; |
127 | |
128 | union { |
129 | struct virtio_mem_req_plug plug; |
130 | struct virtio_mem_req_unplug unplug; |
131 | struct virtio_mem_req_state state; |
132 | } u; |
133 | }; |
134 | |
135 | |
136 | /* --- virtio-mem: host -> guest response --- */ |
137 | |
138 | /* |
139 | * Request processed successfully, applicable for |
140 | * - VIRTIO_MEM_REQ_PLUG |
141 | * - VIRTIO_MEM_REQ_UNPLUG |
142 | * - VIRTIO_MEM_REQ_UNPLUG_ALL |
143 | * - VIRTIO_MEM_REQ_STATE |
144 | */ |
145 | #define VIRTIO_MEM_RESP_ACK 0 |
146 | /* |
147 | * Request denied - e.g. trying to plug more than requested, applicable for |
148 | * - VIRTIO_MEM_REQ_PLUG |
149 | */ |
150 | #define VIRTIO_MEM_RESP_NACK 1 |
151 | /* |
152 | * Request cannot be processed right now, try again later, applicable for |
153 | * - VIRTIO_MEM_REQ_PLUG |
154 | * - VIRTIO_MEM_REQ_UNPLUG |
155 | * - VIRTIO_MEM_REQ_UNPLUG_ALL |
156 | */ |
157 | #define VIRTIO_MEM_RESP_BUSY 2 |
158 | /* |
159 | * Error in request (e.g. addresses/alignment), applicable for |
160 | * - VIRTIO_MEM_REQ_PLUG |
161 | * - VIRTIO_MEM_REQ_UNPLUG |
162 | * - VIRTIO_MEM_REQ_STATE |
163 | */ |
164 | #define VIRTIO_MEM_RESP_ERROR 3 |
165 | |
166 | |
167 | /* State of memory blocks is "plugged" */ |
168 | #define VIRTIO_MEM_STATE_PLUGGED 0 |
169 | /* State of memory blocks is "unplugged" */ |
170 | #define VIRTIO_MEM_STATE_UNPLUGGED 1 |
171 | /* State of memory blocks is "mixed" */ |
172 | #define VIRTIO_MEM_STATE_MIXED 2 |
173 | |
174 | struct virtio_mem_resp_state { |
175 | __virtio16 state; |
176 | }; |
177 | |
178 | struct virtio_mem_resp { |
179 | __virtio16 type; |
180 | __virtio16 padding[3]; |
181 | |
182 | union { |
183 | struct virtio_mem_resp_state state; |
184 | } u; |
185 | }; |
186 | |
187 | /* --- virtio-mem: configuration --- */ |
188 | |
189 | struct virtio_mem_config { |
190 | /* Block size and alignment. Cannot change. */ |
191 | __le64 block_size; |
192 | /* Valid with VIRTIO_MEM_F_ACPI_PXM. Cannot change. */ |
193 | __le16 node_id; |
194 | __u8 padding[6]; |
195 | /* Start address of the memory region. Cannot change. */ |
196 | __le64 addr; |
197 | /* Region size (maximum). Cannot change. */ |
198 | __le64 region_size; |
199 | /* |
200 | * Currently usable region size. Can grow up to region_size. Can |
201 | * shrink due to VIRTIO_MEM_REQ_UNPLUG_ALL (in which case no config |
202 | * update will be sent). |
203 | */ |
204 | __le64 usable_region_size; |
205 | /* |
206 | * Currently used size. Changes due to plug/unplug requests, but no |
207 | * config updates will be sent. |
208 | */ |
209 | __le64 plugged_size; |
210 | /* Requested size. New plug requests cannot exceed it. Can change. */ |
211 | __le64 requested_size; |
212 | }; |
213 | |
214 | #endif /* _LINUX_VIRTIO_MEM_H */ |
215 | |