217 lines · c
1/* SPDX-License-Identifier: BSD-3-Clause */2/*3 * Virtio Mem Device4 *5 * Copyright Red Hat, Inc. 20206 *7 * Authors:8 * David Hildenbrand <david@redhat.com>9 *10 * This header is BSD licensed so anyone can use the definitions11 * to implement compatible drivers/servers:12 *13 * Redistribution and use in source and binary forms, with or without14 * modification, are permitted provided that the following conditions15 * are met:16 * 1. Redistributions of source code must retain the above copyright17 * notice, this list of conditions and the following disclaimer.18 * 2. Redistributions in binary form must reproduce the above copyright19 * notice, this list of conditions and the following disclaimer in the20 * documentation and/or other materials provided with the distribution.21 * 3. Neither the name of IBM nor the names of its contributors22 * may be used to endorse or promote products derived from this software23 * without specific prior written permission.24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS25 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT26 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS27 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL IBM OR28 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,29 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT30 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF31 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND32 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,33 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT34 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF35 * SUCH DAMAGE.36 */37 38#ifndef _LINUX_VIRTIO_MEM_H39#define _LINUX_VIRTIO_MEM_H40 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 address48 * space. Each device can belong to a single NUMA node, multiple devices49 * for a single NUMA node are possible. A virtio-mem device is like a50 * "resizable DIMM" consisting of small memory blocks that can be plugged51 * or unplugged. The device driver is responsible for (un)plugging memory52 * blocks on demand.53 *54 * Virtio-mem devices can only operate on their assigned memory region in55 * order to (un)plug memory. A device cannot (un)plug memory belonging to56 * other devices.57 *58 * The "region_size" corresponds to the maximum amount of memory that can59 * be provided by a device. The "size" corresponds to the amount of memory60 * that is currently plugged. "requested_size" corresponds to a request61 * from the device to the device driver to (un)plug blocks. The62 * device driver should try to (un)plug blocks in order to reach the63 * "requested_size". It is impossible to plug more memory than requested.64 *65 * The "usable_region_size" represents the memory region that can actually66 * be used to (un)plug memory. It is always at least as big as the67 * "requested_size" and will grow dynamically. It will only shrink when68 * explicitly triggered (VIRTIO_MEM_REQ_UNPLUG).69 *70 * There are no guarantees what will happen if unplugged memory is71 * read/written. In general, unplugged memory should not be touched, because72 * the resulting action is undefined. There is one exception: without73 * VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE, unplugged memory inside the usable74 * region can be read, to simplify creation of memory dumps.75 *76 * It can happen that the device cannot process a request, because it is77 * busy. The device driver has to retry later.78 *79 * Usually, during system resets all memory will get unplugged, so the80 * device driver can start with a clean state. However, in specific81 * scenarios (if the device is busy) it can happen that the device still82 * has memory plugged. The device driver can request to unplug all memory83 * (VIRTIO_MEM_REQ_UNPLUG) - which might take a while to succeed if the84 * 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 091/* unplugged memory must not be accessed */92#define VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE 193/* plugged memory will remain plugged when suspending+resuming */94#define VIRTIO_MEM_F_PERSISTENT_SUSPEND 295 96 97/* --- virtio-mem: guest -> host requests --- */98 99/* request to plug memory blocks */100#define VIRTIO_MEM_REQ_PLUG 0101/* request to unplug memory blocks */102#define VIRTIO_MEM_REQ_UNPLUG 1103/* request to unplug all blocks and shrink the usable size */104#define VIRTIO_MEM_REQ_UNPLUG_ALL 2105/* request information about the plugged state of memory blocks */106#define VIRTIO_MEM_REQ_STATE 3107 108struct virtio_mem_req_plug {109 __virtio64 addr;110 __virtio16 nb_blocks;111 __virtio16 padding[3];112};113 114struct virtio_mem_req_unplug {115 __virtio64 addr;116 __virtio16 nb_blocks;117 __virtio16 padding[3];118};119 120struct virtio_mem_req_state {121 __virtio64 addr;122 __virtio16 nb_blocks;123 __virtio16 padding[3];124};125 126struct 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 for142 * - VIRTIO_MEM_REQ_PLUG143 * - VIRTIO_MEM_REQ_UNPLUG144 * - VIRTIO_MEM_REQ_UNPLUG_ALL145 * - VIRTIO_MEM_REQ_STATE146 */147#define VIRTIO_MEM_RESP_ACK 0148/*149 * Request denied - e.g. trying to plug more than requested, applicable for150 * - VIRTIO_MEM_REQ_PLUG151 */152#define VIRTIO_MEM_RESP_NACK 1153/*154 * Request cannot be processed right now, try again later, applicable for155 * - VIRTIO_MEM_REQ_PLUG156 * - VIRTIO_MEM_REQ_UNPLUG157 * - VIRTIO_MEM_REQ_UNPLUG_ALL158 */159#define VIRTIO_MEM_RESP_BUSY 2160/*161 * Error in request (e.g. addresses/alignment), applicable for162 * - VIRTIO_MEM_REQ_PLUG163 * - VIRTIO_MEM_REQ_UNPLUG164 * - VIRTIO_MEM_REQ_STATE165 */166#define VIRTIO_MEM_RESP_ERROR 3167 168 169/* State of memory blocks is "plugged" */170#define VIRTIO_MEM_STATE_PLUGGED 0171/* State of memory blocks is "unplugged" */172#define VIRTIO_MEM_STATE_UNPLUGGED 1173/* State of memory blocks is "mixed" */174#define VIRTIO_MEM_STATE_MIXED 2175 176struct virtio_mem_resp_state {177 __virtio16 state;178};179 180struct 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 191struct 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. Can203 * shrink due to VIRTIO_MEM_REQ_UNPLUG_ALL (in which case no config204 * update will be sent).205 */206 __le64 usable_region_size;207 /*208 * Currently used size. Changes due to plug/unplug requests, but no209 * 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