Documentation/userspace-api/vduse.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/vduse.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/vduse.rst
Extension
.rst
Size
8914 bytes
Lines
287
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

switch (req.type) {

		/* handle different types of messages */

		}

		len = write(dev_fd, &resp, sizeof(resp));
		if (len != sizeof(resp))
			return -1;

		return 0;
	}

There are now three types of messages introduced by VDUSE framework:

- VDUSE_GET_VQ_STATE: Get the state for virtqueue, userspace should return
  avail index for split virtqueue or the device/driver ring wrap counters and
  the avail and used index for packed virtqueue.

- VDUSE_SET_STATUS: Set the device status, userspace should follow
  the virtio spec: https://docs.oasis-open.org/virtio/virtio/v1.1/virtio-v1.1.html
  to process this message. For example, fail to set the FEATURES_OK device
  status bit if the device can not accept the negotiated virtio features
  get from the VDUSE_DEV_GET_FEATURES ioctl.

- VDUSE_UPDATE_IOTLB: Notify userspace to update the memory mapping for specified
  IOVA range, userspace should firstly remove the old mapping, then setup the new
  mapping via the VDUSE_IOTLB_GET_FD ioctl.

After DRIVER_OK status bit is set via the VDUSE_SET_STATUS message, userspace is
able to start the dataplane processing as follows:

1. Get the specified virtqueue's information with the VDUSE_VQ_GET_INFO ioctl,
   including the size, the IOVAs of descriptor table, available ring and used ring,
   the state and the ready status.

2. Pass the above IOVAs to the VDUSE_IOTLB_GET_FD ioctl so that those IOVA regions
   can be mapped into userspace. Some sample codes is shown below:

.. code-block:: c

	static int perm_to_prot(uint8_t perm)
	{
		int prot = 0;

		switch (perm) {
		case VDUSE_ACCESS_WO:
			prot |= PROT_WRITE;
			break;
		case VDUSE_ACCESS_RO:
			prot |= PROT_READ;
			break;
		case VDUSE_ACCESS_RW:
			prot |= PROT_READ | PROT_WRITE;
			break;
		}

		return prot;
	}

	static void *iova_to_va(int dev_fd, uint64_t iova, uint64_t *len)
	{
		int fd;
		void *addr;
		size_t size;
		struct vduse_iotlb_entry entry;

		entry.start = iova;
		entry.last = iova;

Annotation

Implementation Notes