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 "standard-headers/linux/types.h" 42 #include "standard-headers/linux/virtio_types.h" 43 #include "standard-headers/linux/virtio_ids.h" 44 #include "standard-headers/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 uint64_t block_size; 194 /* Valid with VIRTIO_MEM_F_ACPI_PXM. Cannot change. */ 195 uint16_t node_id; 196 uint8_t padding[6]; 197 /* Start address of the memory region. Cannot change. */ 198 uint64_t addr; 199 /* Region size (maximum). Cannot change. */ 200 uint64_t 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 uint64_t usable_region_size; 207 /* 208 * Currently used size. Changes due to plug/unplug requests, but no 209 * config updates will be sent. 210 */ 211 uint64_t plugged_size; 212 /* Requested size. New plug requests cannot exceed it. Can change. */ 213 uint64_t requested_size; 214 }; 215 216 #endif /* _LINUX_VIRTIO_MEM_H */ 217