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
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 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. Similarly, you can use
+ioctl(VDUSE_IOTLB_GET_FD2) to obtain the file descriptor describing an IOVA
+region of an 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
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
On Thu, Jan 15, 2026 at 9:41 AM Michael S. Tsirkin <mst@redhat.com> wrote:
>
> 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.
Fixing typos for the next version, thanks!
On Thu, Jan 15, 2026 at 2:49 AM Eugenio Pérez <eperezma@redhat.com> 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
> 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 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. Similarly, you can use
Should be "querying"
> +ioctl(VDUSE_IOTLB_GET_FD2) to obtain the file descriptor describing an IOVA
Should we fail VDUSE_IOTLB_GET_FD on API version 1 or it is implied for ASID 0?
> +region of an 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;
> + }
> +
It looks like we missed the documentation of VDUSE_SET_VQ_GROUP_ASID.
> For more details on the uAPI, please see include/uapi/linux/vduse.h.
> --
> 2.52.0
>
Thanks
On Thu, Jan 15, 2026 at 9:15 AM Jason Wang <jasowang@redhat.com> wrote:
>
> On Thu, Jan 15, 2026 at 2:49 AM Eugenio Pérez <eperezma@redhat.com> 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
> > 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 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. Similarly, you can use
>
> Should be "querying"
>
> > +ioctl(VDUSE_IOTLB_GET_FD2) to obtain the file descriptor describing an IOVA
>
> Should we fail VDUSE_IOTLB_GET_FD on API version 1 or it is implied for ASID 0?
>
ASID 0 is implied at this moment, so future VDUSE devices don't need
to worry about ASID configuration.
> > +region of an 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;
> > + }
> > +
>
> It looks like we missed the documentation of VDUSE_SET_VQ_GROUP_ASID.
>
> > For more details on the uAPI, please see include/uapi/linux/vduse.h.
> > --
> > 2.52.0
> >
>
> Thanks
>
On Thu, Jan 15, 2026 at 9:15 AM Jason Wang <jasowang@redhat.com> wrote:
>
> On Thu, Jan 15, 2026 at 2:49 AM Eugenio Pérez <eperezma@redhat.com> 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
> > 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 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. Similarly, you can use
>
> Should be "querying"
>
Right, fixing the typos for the next version, thanks!
> > +ioctl(VDUSE_IOTLB_GET_FD2) to obtain the file descriptor describing an IOVA
>
> Should we fail VDUSE_IOTLB_GET_FD on API version 1 or it is implied for ASID 0?
>
> > +region of an 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;
> > + }
> > +
>
> It looks like we missed the documentation of VDUSE_SET_VQ_GROUP_ASID.
>
Sure, adding it for the next version. Thanks!
© 2016 - 2026 Red Hat, Inc.