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