Re: [PATCH v12 13/13] Documentation: Add documentation for VDUSE Address Space IDs

["Michael S. Tsirkin" <mst@redhat.com>]

On Wed, Jan 14, 2026 at 07:48:39PM +0100, Eugenio Pérez wrote:
> Address Space IDs allows the VDUSE framework to support devices able to
> expose different virtqueues to different part of the drivers.  For
> example, to let QEMU handle the net device control virtqueue, so QEMU
> always knows the state of the device like mac address or number of
> queues enabled, while leaving the dataplane passtrhough to the guest

passthrough

> intact.  This enables live migration.
> 
> Expands the VDUSE documentation to explain how to use the new ioctls or
> the new struct members of old ioctls.
> 
> Signed-off-by: Eugenio Pérez <eperezma@redhat.com>
> ---
> v12: New in V12. Requested by Jason.
> ---
>  Documentation/userspace-api/vduse.rst | 49 +++++++++++++++++++++++++++
>  1 file changed, 49 insertions(+)
> 
> diff --git a/Documentation/userspace-api/vduse.rst b/Documentation/userspace-api/vduse.rst
> index bdb880e01132..66110d918815 100644
> --- a/Documentation/userspace-api/vduse.rst
> +++ b/Documentation/userspace-api/vduse.rst
> @@ -230,4 +230,53 @@ able to start the dataplane processing as follows:
>  5. Inject an interrupt for specific virtqueue with the VDUSE_INJECT_VQ_IRQ ioctl
>     after the used ring is filled.
>  
> +Enabling ASID (API version 1)
> +------------------------------
> +
> +VDUSE supports per-address-space identifiers (ASIDs) starting with API
> +version 1. Setup it

Set it up

> with ioctl(VDUSE_SET_API_VERSION) on `/dev/vduse/control` and
> +pass `VDUSE_API_VERSION_1` before creating a new VDUSE instance with
> +ioctl(VDUSE_CREATE_DEV).
> +
> +Afterwards, you can use the member asid of ioctl(VDUSE_IOTLB_GET_INFO) to
> +select the address space of the IOTLB you are queryng.

querying

> Similarly, you can use
> +ioctl(VDUSE_IOTLB_GET_FD2) to obtain the file descriptor describing an IOVA
> +region of an specific ASID. Example usage:

a specific

> +
> +.. code-block:: c
> +
> +	static void *iova_to_va(int dev_fd, uint32_t asid, uint64_t iova,
> +	                        uint64_t *len)
> +	{
> +		int fd;
> +		void *addr;
> +		size_t size;
> +		struct vduse_iotlb_entry_v2 entry = { 0 };
> +
> +		entry.v1.start = iova;
> +		entry.v1.last = iova;
> +		entry.asid = asid;
> +
> +		fd = ioctl(dev_fd, VDUSE_IOTLB_GET_FD2, &entry);
> +		if (fd < 0)
> +			return NULL;
> +
> +		size = entry.v1.last - entry.v1.start + 1;
> +		*len = entry.v1.last - iova + 1;
> +		addr = mmap(0, size, perm_to_prot(entry.v1.perm), MAP_SHARED,
> +			    fd, entry.v1.offset);
> +		close(fd);
> +		if (addr == MAP_FAILED)
> +			return NULL;
> +
> +		/*
> +		 * Using some data structures such as linked list to store
> +		 * the iotlb mapping. The munmap(2) should be called for the
> +		 * cached mapping when the corresponding VDUSE_UPDATE_IOTLB
> +		 * message is received or the device is reset.
> +		 */
> +
> +		return addr + iova - entry.start;
> +	}
> +
>  For more details on the uAPI, please see include/uapi/linux/vduse.h.
> -- 
> 2.52.0