1 /* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) */ 2 #ifndef _UAPI_VDUSE_H_ 3 #define _UAPI_VDUSE_H_ 4 5 #include <linux/types.h> 6 7 #define VDUSE_BASE 0x81 8 9 /* The ioctls for control device (/dev/vduse/control) */ 10 11 #define VDUSE_API_VERSION 0 12 13 /* VQ groups and ASID support */ 14 15 #define VDUSE_API_VERSION_1 1 16 17 /* The VDUSE instance expects a request for vq ready */ 18 #define VDUSE_F_QUEUE_READY 0 19 20 /* The VDUSE instance expects a request for suspend */ 21 #define VDUSE_F_SUSPEND 1 22 23 /* 24 * Get the version of VDUSE API that kernel supported (VDUSE_API_VERSION). 25 * This is used for future extension. 26 */ 27 #define VDUSE_GET_API_VERSION _IOR(VDUSE_BASE, 0x00, __u64) 28 29 /* Set the version of VDUSE API that userspace supported. */ 30 #define VDUSE_SET_API_VERSION _IOW(VDUSE_BASE, 0x01, __u64) 31 32 /** 33 * struct vduse_dev_config - basic configuration of a VDUSE device 34 * @name: VDUSE device name, needs to be NUL terminated 35 * @vendor_id: virtio vendor id 36 * @device_id: virtio device id 37 * @features: virtio features 38 * @vq_num: the number of virtqueues 39 * @vq_align: the allocation alignment of virtqueue's metadata 40 * @ngroups: number of vq groups that VDUSE device declares 41 * @nas: number of address spaces that VDUSE device declares 42 * @reserved: for future use, needs to be initialized to zero 43 * @config_size: the size of the configuration space 44 * @config: the buffer of the configuration space 45 * 46 * Structure used by VDUSE_CREATE_DEV ioctl to create VDUSE device. 47 */ 48 struct vduse_dev_config { 49 #define VDUSE_NAME_MAX 256 50 char name[VDUSE_NAME_MAX]; 51 __u32 vendor_id; 52 __u32 device_id; 53 __u64 features; 54 __u32 vq_num; 55 __u32 vq_align; 56 __u32 ngroups; /* if VDUSE_API_VERSION >= 1 */ 57 __u32 nas; /* if VDUSE_API_VERSION >= 1 */ 58 __u32 reserved[11]; 59 __u32 config_size; 60 __u8 config[]; 61 }; 62 63 /* Create a VDUSE device which is represented by a char device (/dev/vduse/$NAME) */ 64 #define VDUSE_CREATE_DEV _IOW(VDUSE_BASE, 0x02, struct vduse_dev_config) 65 66 /* 67 * Destroy a VDUSE device. Make sure there are no more references 68 * to the char device (/dev/vduse/$NAME). 69 */ 70 #define VDUSE_DESTROY_DEV _IOW(VDUSE_BASE, 0x03, char[VDUSE_NAME_MAX]) 71 72 /* Get the VDUSE supported features */ 73 #define VDUSE_GET_FEATURES _IOR(VDUSE_BASE, 0x04, __u64) 74 75 /* Set the VDUSE features */ 76 #define VDUSE_SET_FEATURES _IOW(VDUSE_BASE, 0x05, __u64) 77 78 /* The ioctls for VDUSE device (/dev/vduse/$NAME) */ 79 80 /** 81 * struct vduse_iotlb_entry - entry of IOTLB to describe one IOVA region [start, last] 82 * @offset: the mmap offset on returned file descriptor 83 * @start: start of the IOVA region 84 * @last: last of the IOVA region 85 * @perm: access permission of the IOVA region 86 * 87 * Structure used by VDUSE_IOTLB_GET_FD ioctl to find an overlapped IOVA region. 88 */ 89 struct vduse_iotlb_entry { 90 __u64 offset; 91 __u64 start; 92 __u64 last; 93 #define VDUSE_ACCESS_RO 0x1 94 #define VDUSE_ACCESS_WO 0x2 95 #define VDUSE_ACCESS_RW 0x3 96 __u8 perm; 97 }; 98 99 /* 100 * Find the first IOVA region that overlaps with the range [start, last] 101 * and return the corresponding file descriptor. Return -EINVAL means the 102 * IOVA region doesn't exist. Caller should set start and last fields. 103 */ 104 #define VDUSE_IOTLB_GET_FD _IOWR(VDUSE_BASE, 0x10, struct vduse_iotlb_entry) 105 106 /* 107 * Get the negotiated virtio features. It's a subset of the features in 108 * struct vduse_dev_config which can be accepted by virtio driver. It's 109 * only valid after FEATURES_OK status bit is set. 110 */ 111 #define VDUSE_DEV_GET_FEATURES _IOR(VDUSE_BASE, 0x11, __u64) 112 113 /** 114 * struct vduse_config_data - data used to update configuration space 115 * @offset: the offset from the beginning of configuration space 116 * @length: the length to write to configuration space 117 * @buffer: the buffer used to write from 118 * 119 * Structure used by VDUSE_DEV_SET_CONFIG ioctl to update device 120 * configuration space. 121 */ 122 struct vduse_config_data { 123 __u32 offset; 124 __u32 length; 125 __u8 buffer[]; 126 }; 127 128 /* Set device configuration space */ 129 #define VDUSE_DEV_SET_CONFIG _IOW(VDUSE_BASE, 0x12, struct vduse_config_data) 130 131 /* 132 * Inject a config interrupt. It's usually used to notify virtio driver 133 * that device configuration space has changed. 134 */ 135 #define VDUSE_DEV_INJECT_CONFIG_IRQ _IO(VDUSE_BASE, 0x13) 136 137 /** 138 * struct vduse_vq_config - basic configuration of a virtqueue 139 * @index: virtqueue index 140 * @max_size: the max size of virtqueue 141 * @reserved1: for future use, needs to be initialized to zero 142 * @group: virtqueue group 143 * @reserved2: for future use, needs to be initialized to zero 144 * 145 * Structure used by VDUSE_VQ_SETUP ioctl to setup a virtqueue. 146 */ 147 struct vduse_vq_config { 148 __u32 index; 149 __u16 max_size; 150 __u16 reserved1; 151 __u32 group; 152 __u16 reserved2[10]; 153 }; 154 155 /* 156 * Setup the specified virtqueue. Make sure all virtqueues have been 157 * configured before the device is attached to vDPA bus. 158 */ 159 #define VDUSE_VQ_SETUP _IOW(VDUSE_BASE, 0x14, struct vduse_vq_config) 160 161 /** 162 * struct vduse_vq_state_split - split virtqueue state 163 * @avail_index: available index 164 */ 165 struct vduse_vq_state_split { 166 __u16 avail_index; 167 }; 168 169 /** 170 * struct vduse_vq_state_packed - packed virtqueue state 171 * @last_avail_counter: last driver ring wrap counter observed by device 172 * @last_avail_idx: device available index 173 * @last_used_counter: device ring wrap counter 174 * @last_used_idx: used index 175 */ 176 struct vduse_vq_state_packed { 177 __u16 last_avail_counter; 178 __u16 last_avail_idx; 179 __u16 last_used_counter; 180 __u16 last_used_idx; 181 }; 182 183 /** 184 * struct vduse_vq_group_asid - virtqueue group ASID 185 * @group: Index of the virtqueue group 186 * @asid: Address space ID of the group 187 */ 188 struct vduse_vq_group_asid { 189 __u32 group; 190 __u32 asid; 191 }; 192 193 /** 194 * struct vduse_vq_info - information of a virtqueue 195 * @index: virtqueue index 196 * @num: the size of virtqueue 197 * @desc_addr: address of desc area 198 * @driver_addr: address of driver area 199 * @device_addr: address of device area 200 * @split: split virtqueue state 201 * @packed: packed virtqueue state 202 * @ready: ready status of virtqueue 203 * 204 * Structure used by VDUSE_VQ_GET_INFO ioctl to get virtqueue's information. 205 */ 206 struct vduse_vq_info { 207 __u32 index; 208 __u32 num; 209 __u64 desc_addr; 210 __u64 driver_addr; 211 __u64 device_addr; 212 union { 213 struct vduse_vq_state_split split; 214 struct vduse_vq_state_packed packed; 215 }; 216 __u8 ready; 217 }; 218 219 /* Get the specified virtqueue's information. Caller should set index field. */ 220 #define VDUSE_VQ_GET_INFO _IOWR(VDUSE_BASE, 0x15, struct vduse_vq_info) 221 222 /** 223 * struct vduse_vq_eventfd - eventfd configuration for a virtqueue 224 * @index: virtqueue index 225 * @fd: eventfd, -1 means de-assigning the eventfd 226 * 227 * Structure used by VDUSE_VQ_SETUP_KICKFD ioctl to setup kick eventfd. 228 */ 229 struct vduse_vq_eventfd { 230 __u32 index; 231 #define VDUSE_EVENTFD_DEASSIGN -1 232 int fd; 233 }; 234 235 /* 236 * Setup kick eventfd for specified virtqueue. The kick eventfd is used 237 * by VDUSE kernel module to notify userspace to consume the avail vring. 238 */ 239 #define VDUSE_VQ_SETUP_KICKFD _IOW(VDUSE_BASE, 0x16, struct vduse_vq_eventfd) 240 241 /* 242 * Inject an interrupt for specific virtqueue. It's used to notify virtio driver 243 * to consume the used vring. 244 */ 245 #define VDUSE_VQ_INJECT_IRQ _IOW(VDUSE_BASE, 0x17, __u32) 246 247 /** 248 * struct vduse_iova_umem - userspace memory configuration for one IOVA region 249 * @uaddr: start address of userspace memory, it must be aligned to page size 250 * @iova: start of the IOVA region 251 * @size: size of the IOVA region 252 * @asid: Address space ID of the IOVA region 253 * @reserved: for future use, needs to be initialized to zero 254 * 255 * Structure used by VDUSE_IOTLB_REG_UMEM and VDUSE_IOTLB_DEREG_UMEM 256 * ioctls to register/de-register userspace memory for IOVA regions 257 */ 258 struct vduse_iova_umem { 259 __u64 uaddr; 260 __u64 iova; 261 __u64 size; 262 __u32 asid; 263 __u32 reserved[5]; 264 }; 265 266 /* Register userspace memory for IOVA regions */ 267 #define VDUSE_IOTLB_REG_UMEM _IOW(VDUSE_BASE, 0x18, struct vduse_iova_umem) 268 269 /* De-register the userspace memory. Caller should set iova and size field. */ 270 #define VDUSE_IOTLB_DEREG_UMEM _IOW(VDUSE_BASE, 0x19, struct vduse_iova_umem) 271 272 /** 273 * struct vduse_iova_info - information of one IOVA region 274 * @start: start of the IOVA region 275 * @last: last of the IOVA region 276 * @capability: capability of the IOVA region 277 * @asid: Address space ID of the IOVA region, only if device API version >= 1 278 * @reserved: for future use, needs to be initialized to zero 279 * 280 * Structure used by VDUSE_IOTLB_GET_INFO ioctl to get information of 281 * one IOVA region. 282 */ 283 struct vduse_iova_info { 284 __u64 start; 285 __u64 last; 286 #define VDUSE_IOVA_CAP_UMEM (1 << 0) 287 __u64 capability; 288 __u32 asid; /* Only if device API version >= 1 */ 289 __u32 reserved[5]; 290 }; 291 292 /* 293 * Find the first IOVA region that overlaps with the range [start, last] 294 * and return some information on it. Caller should set start and last fields. 295 */ 296 #define VDUSE_IOTLB_GET_INFO _IOWR(VDUSE_BASE, 0x1a, struct vduse_iova_info) 297 298 /** 299 * struct vduse_iotlb_entry_v2 - entry of IOTLB to describe one IOVA region 300 * 301 * @v1: the original vduse_iotlb_entry 302 * @asid: address space ID of the IOVA region 303 * @reserved: for future use, needs to be initialized to zero 304 * 305 * Structure used by VDUSE_IOTLB_GET_FD2 ioctl to find an overlapped IOVA region. 306 */ 307 struct vduse_iotlb_entry_v2 { 308 __u64 offset; 309 __u64 start; 310 __u64 last; 311 __u8 perm; 312 __u8 padding[7]; 313 __u32 asid; 314 __u32 reserved[11]; 315 }; 316 317 /* 318 * Same as VDUSE_IOTLB_GET_FD but with vduse_iotlb_entry_v2 argument that 319 * support extra fields. 320 */ 321 #define VDUSE_IOTLB_GET_FD2 _IOWR(VDUSE_BASE, 0x1b, struct vduse_iotlb_entry_v2) 322 323 324 /* The control messages definition for read(2)/write(2) on /dev/vduse/$NAME */ 325 326 /** 327 * enum vduse_req_type - request type 328 * @VDUSE_GET_VQ_STATE: get the state for specified virtqueue from userspace 329 * @VDUSE_SET_STATUS: set the device status 330 * @VDUSE_UPDATE_IOTLB: Notify userspace to update the memory mapping for 331 * specified IOVA range via VDUSE_IOTLB_GET_FD ioctl 332 * @VDUSE_SET_VQ_GROUP_ASID: Notify userspace to update the address space of a 333 * virtqueue group. 334 */ 335 enum vduse_req_type { 336 VDUSE_GET_VQ_STATE, 337 VDUSE_SET_STATUS, 338 VDUSE_UPDATE_IOTLB, 339 VDUSE_SET_VQ_GROUP_ASID, 340 VDUSE_SET_VQ_READY, 341 VDUSE_SUSPEND, 342 }; 343 344 /** 345 * struct vduse_vq_state - virtqueue state 346 * @index: virtqueue index 347 * @split: split virtqueue state 348 * @packed: packed virtqueue state 349 */ 350 struct vduse_vq_state { 351 __u32 index; 352 union { 353 struct vduse_vq_state_split split; 354 struct vduse_vq_state_packed packed; 355 }; 356 }; 357 358 /** 359 * struct vduse_dev_status - device status 360 * @status: device status 361 */ 362 struct vduse_dev_status { 363 __u8 status; 364 }; 365 366 /** 367 * struct vduse_iova_range - IOVA range [start, last] 368 * @start: start of the IOVA range 369 * @last: last of the IOVA range 370 */ 371 struct vduse_iova_range { 372 __u64 start; 373 __u64 last; 374 }; 375 376 /** 377 * struct vduse_iova_range_v2 - IOVA range [start, last] if API_VERSION >= 1 378 * @start: start of the IOVA range 379 * @last: last of the IOVA range 380 * @asid: address space ID of the IOVA range 381 */ 382 struct vduse_iova_range_v2 { 383 __u64 start; 384 __u64 last; 385 __u32 asid; 386 __u32 padding; 387 }; 388 389 /** 390 * struct vduse_vq_ready - Virtqueue ready request message 391 * @num: Virtqueue number 392 */ 393 struct vduse_vq_ready { 394 __u32 num; 395 __u32 ready; 396 }; 397 398 /** 399 * struct vduse_dev_request - control request 400 * @type: request type 401 * @request_id: request id 402 * @reserved: for future use 403 * @vq_state: virtqueue state, only index field is available 404 * @s: device status 405 * @iova: IOVA range for updating 406 * @iova_v2: IOVA range for updating if API_VERSION >= 1 407 * @vq_group_asid: ASID of a virtqueue group 408 * @vq_ready: Virtqueue ready request 409 * @padding: padding 410 * 411 * Structure used by read(2) on /dev/vduse/$NAME. 412 */ 413 struct vduse_dev_request { 414 __u32 type; 415 __u32 request_id; 416 __u32 reserved[4]; 417 union { 418 struct vduse_vq_state vq_state; 419 struct vduse_dev_status s; 420 struct vduse_iova_range iova; 421 /* Following members but padding exist only if vduse api 422 * version >= 1 423 */ 424 struct vduse_iova_range_v2 iova_v2; 425 struct vduse_vq_group_asid vq_group_asid; 426 427 /* Only if VDUSE_F_QUEUE_READY is negotiated */ 428 struct vduse_vq_ready vq_ready; 429 430 __u32 padding[32]; 431 }; 432 }; 433 434 /** 435 * struct vduse_dev_response - response to control request 436 * @request_id: corresponding request id 437 * @result: the result of request 438 * @reserved: for future use, needs to be initialized to zero 439 * @vq_state: virtqueue state 440 * @padding: padding 441 * 442 * Structure used by write(2) on /dev/vduse/$NAME. 443 */ 444 struct vduse_dev_response { 445 __u32 request_id; 446 #define VDUSE_REQ_RESULT_OK 0x00 447 #define VDUSE_REQ_RESULT_FAILED 0x01 448 __u32 result; 449 __u32 reserved[4]; 450 union { 451 struct vduse_vq_state vq_state; 452 __u32 padding[32]; 453 }; 454 }; 455 456 #endif /* _UAPI_VDUSE_H_ */ 457