On Fri, Jan 16, 2026 at 10:05 PM Eugenio Pérez <[email protected]> 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 passthrough to the guest
> 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 <[email protected]>
> ---
> v13:
> * Fix s/VDUSE_IOTLB_GET_INFO/VDUSE_VQ_SETUP/.
> * Document VDUSE_SET_VQ_GROUP_ASID VDUSE message (Jason).
> * Fix typos (MST and Jason).
>
> v12: New in V12. Requested by Jason.
> ---
> Documentation/userspace-api/vduse.rst | 53 +++++++++++++++++++++++++++
> 1 file changed, 53 insertions(+)
>
> diff --git a/Documentation/userspace-api/vduse.rst
> b/Documentation/userspace-api/vduse.rst
> index bdb880e01132..aa067da92cf5 100644
> --- a/Documentation/userspace-api/vduse.rst
> +++ b/Documentation/userspace-api/vduse.rst
> @@ -230,4 +230,57 @@ 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. 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_VQ_SETUP) argument to
> +select the address space of the IOTLB you are querying. The driver could
> +change the address space of any virtqueue group by using the
> +VDUSE_SET_VQ_GROUP_ASID VDUSE message type, and the VDUSE instance needs to
> +reply with VDUSE_REQ_RESULT_OK if it was possible to change it.
Nitpick: Is this better to move this to the part of
"There are now three types of messages introduced by VDUSE framework:"
?
> +
> +Similarly, you can use ioctl(VDUSE_IOTLB_GET_FD2) to obtain the file
> descriptor
> +describing an IOVA region of a specific ASID. Example usage:
> +
> +.. 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
>
Thanks
