uapi/linux/vduse.h

0001 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
0002 #ifndef _UAPI_VDUSE_H_
0003 #define _UAPI_VDUSE_H_
0004
0005 #include <linux/types.h>
0006
0007 #define VDUSE_BASE  0x81
0008
0009 /* The ioctls for control device (/dev/vduse/control) */
0010
0011 #define VDUSE_API_VERSION   0
0012
0013 /*
0014  * Get the version of VDUSE API that kernel supported (VDUSE_API_VERSION).
0015  * This is used for future extension.
0016  */
0017 #define VDUSE_GET_API_VERSION   _IOR(VDUSE_BASE, 0x00, __u64)
0018
0019 /* Set the version of VDUSE API that userspace supported. */
0020 #define VDUSE_SET_API_VERSION   _IOW(VDUSE_BASE, 0x01, __u64)
0021
0022 /**
0023  * struct vduse_dev_config - basic configuration of a VDUSE device
0024  * @name: VDUSE device name, needs to be NUL terminated
0025  * @vendor_id: virtio vendor id
0026  * @device_id: virtio device id
0027  * @features: virtio features
0028  * @vq_num: the number of virtqueues
0029  * @vq_align: the allocation alignment of virtqueue's metadata
0030  * @reserved: for future use, needs to be initialized to zero
0031  * @config_size: the size of the configuration space
0032  * @config: the buffer of the configuration space
0033  *
0034  * Structure used by VDUSE_CREATE_DEV ioctl to create VDUSE device.
0035  */
0036 struct vduse_dev_config {
0037 #define VDUSE_NAME_MAX  256
0038     char name[VDUSE_NAME_MAX];
0039     __u32 vendor_id;
0040     __u32 device_id;
0041     __u64 features;
0042     __u32 vq_num;
0043     __u32 vq_align;
0044     __u32 reserved[13];
0045     __u32 config_size;
0046     __u8 config[];
0047 };
0048
0049 /* Create a VDUSE device which is represented by a char device (/dev/vduse/$NAME) */
0050 #define VDUSE_CREATE_DEV    _IOW(VDUSE_BASE, 0x02, struct vduse_dev_config)
0051
0052 /*
0053  * Destroy a VDUSE device. Make sure there are no more references
0054  * to the char device (/dev/vduse/$NAME).
0055  */
0056 #define VDUSE_DESTROY_DEV   _IOW(VDUSE_BASE, 0x03, char[VDUSE_NAME_MAX])
0057
0058 /* The ioctls for VDUSE device (/dev/vduse/$NAME) */
0059
0060 /**
0061  * struct vduse_iotlb_entry - entry of IOTLB to describe one IOVA region [start, last]
0062  * @offset: the mmap offset on returned file descriptor
0063  * @start: start of the IOVA region
0064  * @last: last of the IOVA region
0065  * @perm: access permission of the IOVA region
0066  *
0067  * Structure used by VDUSE_IOTLB_GET_FD ioctl to find an overlapped IOVA region.
0068  */
0069 struct vduse_iotlb_entry {
0070     __u64 offset;
0071     __u64 start;
0072     __u64 last;
0073 #define VDUSE_ACCESS_RO 0x1
0074 #define VDUSE_ACCESS_WO 0x2
0075 #define VDUSE_ACCESS_RW 0x3
0076     __u8 perm;
0077 };
0078
0079 /*
0080  * Find the first IOVA region that overlaps with the range [start, last]
0081  * and return the corresponding file descriptor. Return -EINVAL means the
0082  * IOVA region doesn't exist. Caller should set start and last fields.
0083  */
0084 #define VDUSE_IOTLB_GET_FD  _IOWR(VDUSE_BASE, 0x10, struct vduse_iotlb_entry)
0085
0086 /*
0087  * Get the negotiated virtio features. It's a subset of the features in
0088  * struct vduse_dev_config which can be accepted by virtio driver. It's
0089  * only valid after FEATURES_OK status bit is set.
0090  */
0091 #define VDUSE_DEV_GET_FEATURES  _IOR(VDUSE_BASE, 0x11, __u64)
0092
0093 /**
0094  * struct vduse_config_data - data used to update configuration space
0095  * @offset: the offset from the beginning of configuration space
0096  * @length: the length to write to configuration space
0097  * @buffer: the buffer used to write from
0098  *
0099  * Structure used by VDUSE_DEV_SET_CONFIG ioctl to update device
0100  * configuration space.
0101  */
0102 struct vduse_config_data {
0103     __u32 offset;
0104     __u32 length;
0105     __u8 buffer[];
0106 };
0107
0108 /* Set device configuration space */
0109 #define VDUSE_DEV_SET_CONFIG    _IOW(VDUSE_BASE, 0x12, struct vduse_config_data)
0110
0111 /*
0112  * Inject a config interrupt. It's usually used to notify virtio driver
0113  * that device configuration space has changed.
0114  */
0115 #define VDUSE_DEV_INJECT_CONFIG_IRQ _IO(VDUSE_BASE, 0x13)
0116
0117 /**
0118  * struct vduse_vq_config - basic configuration of a virtqueue
0119  * @index: virtqueue index
0120  * @max_size: the max size of virtqueue
0121  * @reserved: for future use, needs to be initialized to zero
0122  *
0123  * Structure used by VDUSE_VQ_SETUP ioctl to setup a virtqueue.
0124  */
0125 struct vduse_vq_config {
0126     __u32 index;
0127     __u16 max_size;
0128     __u16 reserved[13];
0129 };
0130
0131 /*
0132  * Setup the specified virtqueue. Make sure all virtqueues have been
0133  * configured before the device is attached to vDPA bus.
0134  */
0135 #define VDUSE_VQ_SETUP      _IOW(VDUSE_BASE, 0x14, struct vduse_vq_config)
0136
0137 /**
0138  * struct vduse_vq_state_split - split virtqueue state
0139  * @avail_index: available index
0140  */
0141 struct vduse_vq_state_split {
0142     __u16 avail_index;
0143 };
0144
0145 /**
0146  * struct vduse_vq_state_packed - packed virtqueue state
0147  * @last_avail_counter: last driver ring wrap counter observed by device
0148  * @last_avail_idx: device available index
0149  * @last_used_counter: device ring wrap counter
0150  * @last_used_idx: used index
0151  */
0152 struct vduse_vq_state_packed {
0153     __u16 last_avail_counter;
0154     __u16 last_avail_idx;
0155     __u16 last_used_counter;
0156     __u16 last_used_idx;
0157 };
0158
0159 /**
0160  * struct vduse_vq_info - information of a virtqueue
0161  * @index: virtqueue index
0162  * @num: the size of virtqueue
0163  * @desc_addr: address of desc area
0164  * @driver_addr: address of driver area
0165  * @device_addr: address of device area
0166  * @split: split virtqueue state
0167  * @packed: packed virtqueue state
0168  * @ready: ready status of virtqueue
0169  *
0170  * Structure used by VDUSE_VQ_GET_INFO ioctl to get virtqueue's information.
0171  */
0172 struct vduse_vq_info {
0173     __u32 index;
0174     __u32 num;
0175     __u64 desc_addr;
0176     __u64 driver_addr;
0177     __u64 device_addr;
0178     union {
0179         struct vduse_vq_state_split split;
0180         struct vduse_vq_state_packed packed;
0181     };
0182     __u8 ready;
0183 };
0184
0185 /* Get the specified virtqueue's information. Caller should set index field. */
0186 #define VDUSE_VQ_GET_INFO   _IOWR(VDUSE_BASE, 0x15, struct vduse_vq_info)
0187
0188 /**
0189  * struct vduse_vq_eventfd - eventfd configuration for a virtqueue
0190  * @index: virtqueue index
0191  * @fd: eventfd, -1 means de-assigning the eventfd
0192  *
0193  * Structure used by VDUSE_VQ_SETUP_KICKFD ioctl to setup kick eventfd.
0194  */
0195 struct vduse_vq_eventfd {
0196     __u32 index;
0197 #define VDUSE_EVENTFD_DEASSIGN -1
0198     int fd;
0199 };
0200
0201 /*
0202  * Setup kick eventfd for specified virtqueue. The kick eventfd is used
0203  * by VDUSE kernel module to notify userspace to consume the avail vring.
0204  */
0205 #define VDUSE_VQ_SETUP_KICKFD   _IOW(VDUSE_BASE, 0x16, struct vduse_vq_eventfd)
0206
0207 /*
0208  * Inject an interrupt for specific virtqueue. It's used to notify virtio driver
0209  * to consume the used vring.
0210  */
0211 #define VDUSE_VQ_INJECT_IRQ _IOW(VDUSE_BASE, 0x17, __u32)
0212
0213 /**
0214  * struct vduse_iova_umem - userspace memory configuration for one IOVA region
0215  * @uaddr: start address of userspace memory, it must be aligned to page size
0216  * @iova: start of the IOVA region
0217  * @size: size of the IOVA region
0218  * @reserved: for future use, needs to be initialized to zero
0219  *
0220  * Structure used by VDUSE_IOTLB_REG_UMEM and VDUSE_IOTLB_DEREG_UMEM
0221  * ioctls to register/de-register userspace memory for IOVA regions
0222  */
0223 struct vduse_iova_umem {
0224     __u64 uaddr;
0225     __u64 iova;
0226     __u64 size;
0227     __u64 reserved[3];
0228 };
0229
0230 /* Register userspace memory for IOVA regions */
0231 #define VDUSE_IOTLB_REG_UMEM    _IOW(VDUSE_BASE, 0x18, struct vduse_iova_umem)
0232
0233 /* De-register the userspace memory. Caller should set iova and size field. */
0234 #define VDUSE_IOTLB_DEREG_UMEM  _IOW(VDUSE_BASE, 0x19, struct vduse_iova_umem)
0235
0236 /**
0237  * struct vduse_iova_info - information of one IOVA region
0238  * @start: start of the IOVA region
0239  * @last: last of the IOVA region
0240  * @capability: capability of the IOVA regsion
0241  * @reserved: for future use, needs to be initialized to zero
0242  *
0243  * Structure used by VDUSE_IOTLB_GET_INFO ioctl to get information of
0244  * one IOVA region.
0245  */
0246 struct vduse_iova_info {
0247     __u64 start;
0248     __u64 last;
0249 #define VDUSE_IOVA_CAP_UMEM (1 << 0)
0250     __u64 capability;
0251     __u64 reserved[3];
0252 };
0253
0254 /*
0255  * Find the first IOVA region that overlaps with the range [start, last]
0256  * and return some information on it. Caller should set start and last fields.
0257  */
0258 #define VDUSE_IOTLB_GET_INFO    _IOWR(VDUSE_BASE, 0x1a, struct vduse_iova_info)
0259
0260 /* The control messages definition for read(2)/write(2) on /dev/vduse/$NAME */
0261
0262 /**
0263  * enum vduse_req_type - request type
0264  * @VDUSE_GET_VQ_STATE: get the state for specified virtqueue from userspace
0265  * @VDUSE_SET_STATUS: set the device status
0266  * @VDUSE_UPDATE_IOTLB: Notify userspace to update the memory mapping for
0267  *                      specified IOVA range via VDUSE_IOTLB_GET_FD ioctl
0268  */
0269 enum vduse_req_type {
0270     VDUSE_GET_VQ_STATE,
0271     VDUSE_SET_STATUS,
0272     VDUSE_UPDATE_IOTLB,
0273 };
0274
0275 /**
0276  * struct vduse_vq_state - virtqueue state
0277  * @index: virtqueue index
0278  * @split: split virtqueue state
0279  * @packed: packed virtqueue state
0280  */
0281 struct vduse_vq_state {
0282     __u32 index;
0283     union {
0284         struct vduse_vq_state_split split;
0285         struct vduse_vq_state_packed packed;
0286     };
0287 };
0288
0289 /**
0290  * struct vduse_dev_status - device status
0291  * @status: device status
0292  */
0293 struct vduse_dev_status {
0294     __u8 status;
0295 };
0296
0297 /**
0298  * struct vduse_iova_range - IOVA range [start, last]
0299  * @start: start of the IOVA range
0300  * @last: last of the IOVA range
0301  */
0302 struct vduse_iova_range {
0303     __u64 start;
0304     __u64 last;
0305 };
0306
0307 /**
0308  * struct vduse_dev_request - control request
0309  * @type: request type
0310  * @request_id: request id
0311  * @reserved: for future use
0312  * @vq_state: virtqueue state, only index field is available
0313  * @s: device status
0314  * @iova: IOVA range for updating
0315  * @padding: padding
0316  *
0317  * Structure used by read(2) on /dev/vduse/$NAME.
0318  */
0319 struct vduse_dev_request {
0320     __u32 type;
0321     __u32 request_id;
0322     __u32 reserved[4];
0323     union {
0324         struct vduse_vq_state vq_state;
0325         struct vduse_dev_status s;
0326         struct vduse_iova_range iova;
0327         __u32 padding[32];
0328     };
0329 };
0330
0331 /**
0332  * struct vduse_dev_response - response to control request
0333  * @request_id: corresponding request id
0334  * @result: the result of request
0335  * @reserved: for future use, needs to be initialized to zero
0336  * @vq_state: virtqueue state
0337  * @padding: padding
0338  *
0339  * Structure used by write(2) on /dev/vduse/$NAME.
0340  */
0341 struct vduse_dev_response {
0342     __u32 request_id;
0343 #define VDUSE_REQ_RESULT_OK 0x00
0344 #define VDUSE_REQ_RESULT_FAILED 0x01
0345     __u32 result;
0346     __u32 reserved[4];
0347     union {
0348         struct vduse_vq_state vq_state;
0349         __u32 padding[32];
0350     };
0351 };
0352
0353 #endif /* _UAPI_VDUSE_H_ */