[linux-2.6-block.git] / include / uapi / linux / virtio_mem.h

/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Virtio Mem Device
 *
 * Copyright Red Hat, Inc. 2020
 *
 * Authors:
 *     David Hildenbrand <david@redhat.com>
 *
 * This header is BSD licensed so anyone can use the definitions
 * to implement compatible drivers/servers:
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of IBM nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL IBM OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 */

#ifndef _LINUX_VIRTIO_MEM_H
#define _LINUX_VIRTIO_MEM_H

#include <linux/types.h>
#include <linux/virtio_types.h>
#include <linux/virtio_ids.h>
#include <linux/virtio_config.h>

/*
 * Each virtio-mem device manages a dedicated region in physical address
 * space. Each device can belong to a single NUMA node, multiple devices
 * for a single NUMA node are possible. A virtio-mem device is like a
 * "resizable DIMM" consisting of small memory blocks that can be plugged
 * or unplugged. The device driver is responsible for (un)plugging memory
 * blocks on demand.
 *
 * Virtio-mem devices can only operate on their assigned memory region in
 * order to (un)plug memory. A device cannot (un)plug memory belonging to
 * other devices.
 *
 * The "region_size" corresponds to the maximum amount of memory that can
 * be provided by a device. The "size" corresponds to the amount of memory
 * that is currently plugged. "requested_size" corresponds to a request
 * from the device to the device driver to (un)plug blocks. The
 * device driver should try to (un)plug blocks in order to reach the
 * "requested_size". It is impossible to plug more memory than requested.
 *
 * The "usable_region_size" represents the memory region that can actually
 * be used to (un)plug memory. It is always at least as big as the
 * "requested_size" and will grow dynamically. It will only shrink when
 * explicitly triggered (VIRTIO_MEM_REQ_UNPLUG).
 *
 * There are no guarantees what will happen if unplugged memory is
 * read/written. In general, unplugged memory should not be touched, because
 * the resulting action is undefined. There is one exception: without
 * VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE, unplugged memory inside the usable
 * region can be read, to simplify creation of memory dumps.
 *
 * It can happen that the device cannot process a request, because it is
 * busy. The device driver has to retry later.
 *
 * Usually, during system resets all memory will get unplugged, so the
 * device driver can start with a clean state. However, in specific
 * scenarios (if the device is busy) it can happen that the device still
 * has memory plugged. The device driver can request to unplug all memory
 * (VIRTIO_MEM_REQ_UNPLUG) - which might take a while to succeed if the
 * device is busy.
 */

/* --- virtio-mem: feature bits --- */

/* node_id is an ACPI PXM and is valid */
#define VIRTIO_MEM_F_ACPI_PXM		0
/* unplugged memory must not be accessed */
#define VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE	1
/* plugged memory will remain plugged when suspending+resuming */
#define VIRTIO_MEM_F_PERSISTENT_SUSPEND		2


/* --- virtio-mem: guest -> host requests --- */

/* request to plug memory blocks */
#define VIRTIO_MEM_REQ_PLUG			0
/* request to unplug memory blocks */
#define VIRTIO_MEM_REQ_UNPLUG			1
/* request to unplug all blocks and shrink the usable size */
#define VIRTIO_MEM_REQ_UNPLUG_ALL		2
/* request information about the plugged state of memory blocks */
#define VIRTIO_MEM_REQ_STATE			3

struct virtio_mem_req_plug {
	__virtio64 addr;
	__virtio16 nb_blocks;
	__virtio16 padding[3];
};

struct virtio_mem_req_unplug {
	__virtio64 addr;
	__virtio16 nb_blocks;
	__virtio16 padding[3];
};

struct virtio_mem_req_state {
	__virtio64 addr;
	__virtio16 nb_blocks;
	__virtio16 padding[3];
};

struct virtio_mem_req {
	__virtio16 type;
	__virtio16 padding[3];

	union {
		struct virtio_mem_req_plug plug;
		struct virtio_mem_req_unplug unplug;
		struct virtio_mem_req_state state;
	} u;
};


/* --- virtio-mem: host -> guest response --- */

/*
 * Request processed successfully, applicable for
 * - VIRTIO_MEM_REQ_PLUG
 * - VIRTIO_MEM_REQ_UNPLUG
 * - VIRTIO_MEM_REQ_UNPLUG_ALL
 * - VIRTIO_MEM_REQ_STATE
 */
#define VIRTIO_MEM_RESP_ACK			0
/*
 * Request denied - e.g. trying to plug more than requested, applicable for
 * - VIRTIO_MEM_REQ_PLUG
 */
#define VIRTIO_MEM_RESP_NACK			1
/*
 * Request cannot be processed right now, try again later, applicable for
 * - VIRTIO_MEM_REQ_PLUG
 * - VIRTIO_MEM_REQ_UNPLUG
 * - VIRTIO_MEM_REQ_UNPLUG_ALL
 */
#define VIRTIO_MEM_RESP_BUSY			2
/*
 * Error in request (e.g. addresses/alignment), applicable for
 * - VIRTIO_MEM_REQ_PLUG
 * - VIRTIO_MEM_REQ_UNPLUG
 * - VIRTIO_MEM_REQ_STATE
 */
#define VIRTIO_MEM_RESP_ERROR			3


/* State of memory blocks is "plugged" */
#define VIRTIO_MEM_STATE_PLUGGED		0
/* State of memory blocks is "unplugged" */
#define VIRTIO_MEM_STATE_UNPLUGGED		1
/* State of memory blocks is "mixed" */
#define VIRTIO_MEM_STATE_MIXED			2

struct virtio_mem_resp_state {
	__virtio16 state;
};

struct virtio_mem_resp {
	__virtio16 type;
	__virtio16 padding[3];

	union {
		struct virtio_mem_resp_state state;
	} u;
};

/* --- virtio-mem: configuration --- */

struct virtio_mem_config {
	/* Block size and alignment. Cannot change. */
	__le64 block_size;
	/* Valid with VIRTIO_MEM_F_ACPI_PXM. Cannot change. */
	__le16 node_id;
	__u8 padding[6];
	/* Start address of the memory region. Cannot change. */
	__le64 addr;
	/* Region size (maximum). Cannot change. */
	__le64 region_size;
	/*
	 * Currently usable region size. Can grow up to region_size. Can
	 * shrink due to VIRTIO_MEM_REQ_UNPLUG_ALL (in which case no config
	 * update will be sent).
	 */
	__le64 usable_region_size;
	/*
	 * Currently used size. Changes due to plug/unplug requests, but no
	 * config updates will be sent.
	 */
	__le64 plugged_size;
	/* Requested size. New plug requests cannot exceed it. Can change. */
	__le64 requested_size;
};

#endif /* _LINUX_VIRTIO_MEM_H */
Commit	Line	Data
5f1f79bb DH	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
61082ad6 DH	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.
5f1f79bb DH	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
f2af6d39 DH	87	/* --- virtio-mem: feature bits --- */
	88
	89	/* node_id is an ACPI PXM and is valid */
	90	#define VIRTIO_MEM_F_ACPI_PXM 0
61082ad6 DH	91	/* unplugged memory must not be accessed */
61082ad6 DH	92	#define VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE 1
e4544c55 DH	93	/* plugged memory will remain plugged when suspending+resuming */
e4544c55 DH	94	#define VIRTIO_MEM_F_PERSISTENT_SUSPEND 2
f2af6d39 DH	95
f2af6d39 DH	96
5f1f79bb DH	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;
fce8afd7	111	__virtio16 padding[3];
5f1f79bb DH	112	};
	113
	114	struct virtio_mem_req_unplug {
	115	__virtio64 addr;
	116	__virtio16 nb_blocks;
fce8afd7	117	__virtio16 padding[3];
5f1f79bb DH	118	};
	119
	120	struct virtio_mem_req_state {
	121	__virtio64 addr;
	122	__virtio16 nb_blocks;
fce8afd7	123	__virtio16 padding[3];
5f1f79bb DH	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. */
79268954	193	__le64 block_size;
f2af6d39	194	/* Valid with VIRTIO_MEM_F_ACPI_PXM. Cannot change. */
79268954	195	__le16 node_id;
544fc7db	196	__u8 padding[6];
5f1f79bb	197	/* Start address of the memory region. Cannot change. */
79268954	198	__le64 addr;
5f1f79bb	199	/* Region size (maximum). Cannot change. */
79268954	200	__le64 region_size;
5f1f79bb DH	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	*/
79268954	206	__le64 usable_region_size;
5f1f79bb DH	207	/*
	208	* Currently used size. Changes due to plug/unplug requests, but no
	209	* config updates will be sent.
	210	*/
79268954	211	__le64 plugged_size;
5f1f79bb	212	/* Requested size. New plug requests cannot exceed it. Can change. */
79268954	213	__le64 requested_size;
5f1f79bb DH	214	};
	215
	216	#endif /* _LINUX_VIRTIO_MEM_H */