[PATCH] qapi/net: deprecate TAP fd and vhostfd options
They are the same as fds and vhostfds, except they accept only one fd. Let's deprecate redundant options. Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> --- Hi all! after "[PATCH v2 00/12] net: refactoring and fixes" options fd and vhostfd becomes redundant, fds and vhostfds may be used instead. this patch also based on "[PATCH v6] qapi: net: deprecate vhostforce option", that's why it's sent separately. Based-on: <20260129213215.1405459-1-vsementsov@yandex-team.ru> Based-on: <20251113071711.349651-1-vsementsov@yandex-team.ru> docs/about/deprecated.rst | 6 ++++++ qapi/net.json | 9 +++++---- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst index e8ff478583..9010f8ab07 100644 --- a/docs/about/deprecated.rst +++ b/docs/about/deprecated.rst @@ -451,6 +451,12 @@ TAP ``vhostforce`` (since 11.0) The ``vhostforce`` option is redundant with the ``vhost`` option. If they conflict, ``vhost`` takes precedence. Just use ``vhost``. +TAP ``fd`` and ``vhostfd`` (since 11.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``fds`` and ``vhostfds`` correspondingly, each set with one fd +instead of ``fd`` and ``vhsotfd``. + Vhost-user ``vhostforce`` (since 11.0) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/qapi/net.json b/qapi/net.json index 9a00d578e9..2d5aed3ef8 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -326,8 +326,7 @@ # # @fd: file descriptor of an already opened tap # -# @fds: multiple file descriptors of already opened multiqueue capable -# tap +# @fds: multiple file descriptors of already opened tap # # @script: script to initialize the interface # @@ -359,13 +358,15 @@ # Features: # # @deprecated: Member @vhostforce is deprecated. Use @vhost instead. +# Member @fd is deprecated. Use @fds instead. +# Member @vhostfd is deprecated. Use @vhostfds instead. # # Since: 1.2 ## { 'struct': 'NetdevTapOptions', 'data': { '*ifname': 'str', - '*fd': 'str', + '*fd': { 'type': 'str', 'features': [ 'deprecated' ] }, '*fds': 'str', '*script': 'str', '*downscript': 'str', @@ -374,7 +375,7 @@ '*sndbuf': 'size', '*vnet_hdr': 'bool', '*vhost': 'bool', - '*vhostfd': 'str', + '*vhostfd': { 'type': 'str', 'features': [ 'deprecated' ] }, '*vhostfds': 'str', '*vhostforce': { 'type': 'bool', 'features': [ 'deprecated' ] }, '*queues': 'uint32', -- 2.52.0
On Fri, Jan 30, 2026 at 00:53:38 +0300, Vladimir Sementsov-Ogievskiy wrote:
They are the same as fds and vhostfds, except they accept only one fd. Let's deprecate redundant options.
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> ---
Hi all!
after "[PATCH v2 00/12] net: refactoring and fixes" options fd and vhostfd becomes redundant, fds and vhostfds may be used instead.
this patch also based on "[PATCH v6] qapi: net: deprecate vhostforce option", that's why it's sent separately.
Based-on: <20260129213215.1405459-1-vsementsov@yandex-team.ru> Based-on: <20251113071711.349651-1-vsementsov@yandex-team.ru>
docs/about/deprecated.rst | 6 ++++++ qapi/net.json | 9 +++++---- 2 files changed, 11 insertions(+), 4 deletions(-)
diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst index e8ff478583..9010f8ab07 100644 --- a/docs/about/deprecated.rst +++ b/docs/about/deprecated.rst @@ -451,6 +451,12 @@ TAP ``vhostforce`` (since 11.0) The ``vhostforce`` option is redundant with the ``vhost`` option. If they conflict, ``vhost`` takes precedence. Just use ``vhost``.
+TAP ``fd`` and ``vhostfd`` (since 11.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``fds`` and ``vhostfds`` correspondingly, each set with one fd +instead of ``fd`` and ``vhsotfd``.
Does this replacement apply/work on all versions supporting vhostfds/fd? I'm asking because libvirt does have code to format the singlular vs plural but none of the versions we support are lacking support for the plural forms so we could replace this unconditionally if it works with older versions.
On 30.01.26 14:44, Peter Krempa wrote:
On Fri, Jan 30, 2026 at 00:53:38 +0300, Vladimir Sementsov-Ogievskiy wrote:
They are the same as fds and vhostfds, except they accept only one fd. Let's deprecate redundant options.
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> ---
Hi all!
after "[PATCH v2 00/12] net: refactoring and fixes" options fd and vhostfd becomes redundant, fds and vhostfds may be used instead.
this patch also based on "[PATCH v6] qapi: net: deprecate vhostforce option", that's why it's sent separately.
Based-on: <20260129213215.1405459-1-vsementsov@yandex-team.ru> Based-on: <20251113071711.349651-1-vsementsov@yandex-team.ru>
docs/about/deprecated.rst | 6 ++++++ qapi/net.json | 9 +++++---- 2 files changed, 11 insertions(+), 4 deletions(-)
diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst index e8ff478583..9010f8ab07 100644 --- a/docs/about/deprecated.rst +++ b/docs/about/deprecated.rst @@ -451,6 +451,12 @@ TAP ``vhostforce`` (since 11.0) The ``vhostforce`` option is redundant with the ``vhost`` option. If they conflict, ``vhost`` takes precedence. Just use ``vhost``.
+TAP ``fd`` and ``vhostfd`` (since 11.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``fds`` and ``vhostfds`` correspondingly, each set with one fd +instead of ``fd`` and ``vhsotfd``.
Does this replacement apply/work on all versions supporting vhostfds/fd?
I'm asking because libvirt does have code to format the singlular vs plural but none of the versions we support are lacking support for the plural forms so we could replace this unconditionally if it works with older versions.
Unfortunately, before "[PATCH v2 00/12] net: refactoring and fixes", some things will not work, if use fds/vhostfds instead of fd/vhostfd for one-queue TAP. Still, probably these cases are not used in Libvirt? 1. Prior the series, tap.c code has check: /* QEMU hubs do not support multiqueue tap, in this case peer is set. * For -netdev, peer is always NULL. */ if (peer && (tap->has_queues || tap->fds || tap->vhostfds)) { error_setg(errp, "Multiqueue tap cannot be used with hubs"); return -1; } This is too restrictive: obviously queues may be set to 1, and fds/vhostfds may contain only one FD, but QEMU doesn't check it. So, this case require fd/vhostfd options, if you want to pass some fds. What this "hub" actually is? As I can see, it's -net cmdline option except for nic: static int net_client_init1(const Netdev *netdev, bool is_netdev, Error **errp) { ... /* Do not add to a hub if it's a nic with a netdev= parameter. */ if (netdev->type != NET_CLIENT_DRIVER_NIC || !netdev->u.nic.netdev) { peer = net_hub_add_port(0, NULL, NULL); } ... } 2. Prior the series, you may pass vhostfds only together with fds. If you want to pass vhostfd for cases without fds, you have to use only vhostfd option. Even for the case when you pass queues > 0, you can't provide vhostfds but only vhostfd (and QEMU will try to reuse it for all queues, which (as I understand) is a bug in current QEMU. -- Best regards, Vladimir
On Fri, Jan 30, 2026 at 15:23:37 +0300, Vladimir Sementsov-Ogievskiy wrote:
On 30.01.26 14:44, Peter Krempa wrote:
On Fri, Jan 30, 2026 at 00:53:38 +0300, Vladimir Sementsov-Ogievskiy wrote:
They are the same as fds and vhostfds, except they accept only one fd. Let's deprecate redundant options.
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> ---
Hi all!
after "[PATCH v2 00/12] net: refactoring and fixes" options fd and vhostfd becomes redundant, fds and vhostfds may be used instead.
this patch also based on "[PATCH v6] qapi: net: deprecate vhostforce option", that's why it's sent separately.
Based-on: <20260129213215.1405459-1-vsementsov@yandex-team.ru> Based-on: <20251113071711.349651-1-vsementsov@yandex-team.ru>
docs/about/deprecated.rst | 6 ++++++ qapi/net.json | 9 +++++---- 2 files changed, 11 insertions(+), 4 deletions(-)
diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst index e8ff478583..9010f8ab07 100644 --- a/docs/about/deprecated.rst +++ b/docs/about/deprecated.rst @@ -451,6 +451,12 @@ TAP ``vhostforce`` (since 11.0) The ``vhostforce`` option is redundant with the ``vhost`` option. If they conflict, ``vhost`` takes precedence. Just use ``vhost``. +TAP ``fd`` and ``vhostfd`` (since 11.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``fds`` and ``vhostfds`` correspondingly, each set with one fd +instead of ``fd`` and ``vhsotfd``.
Does this replacement apply/work on all versions supporting vhostfds/fd?
I'm asking because libvirt does have code to format the singlular vs plural but none of the versions we support are lacking support for the plural forms so we could replace this unconditionally if it works with older versions.
Unfortunately, before "[PATCH v2 00/12] net: refactoring and fixes", some things will not work, if use fds/vhostfds instead of fd/vhostfd for one-queue TAP. Still, probably these cases are not used in Libvirt?
In that case any caveats should IMO be documented in the deprecation document.
for one-queue TAP. Still, probably these cases are not used in Libvirt?
Note that the network stuff in libvirt isn't my specialization so I might be missing stuff that was not metioned explicitly.
1. Prior the series, tap.c code has check:
/* QEMU hubs do not support multiqueue tap, in this case peer is set. * For -netdev, peer is always NULL. */ if (peer && (tap->has_queues || tap->fds || tap->vhostfds)) { error_setg(errp, "Multiqueue tap cannot be used with hubs"); return -1; }
So if that comment is accurate we only use fd/vhostfd with -netdev so this won't trigger in libvirt.
This is too restrictive: obviously queues may be set to 1, and fds/vhostfds may contain only one FD, but QEMU doesn't check it.
So, this case require fd/vhostfd options, if you want to pass some fds.
What this "hub" actually is? As I can see, it's -net cmdline option except for nic:
static int net_client_init1(const Netdev *netdev, bool is_netdev, Error **errp) { ... /* Do not add to a hub if it's a nic with a netdev= parameter. */ if (netdev->type != NET_CLIENT_DRIVER_NIC || !netdev->u.nic.netdev) { peer = net_hub_add_port(0, NULL, NULL); } ... }
2. Prior the series, you may pass vhostfds only together with fds. If you want to pass vhostfd for cases without fds, you have to use only vhostfd option.
So in the test data we seem to be using vhostfd only with fd (or the crresponding plural form) but I'm not 100% sure based on the fact that the formatters for the option are conditional on whether the FDs were opened first. The code opening the FDs seems to open 'vhostfd' only when 'fd' are populated. So if the above is the case (as in 'vhostfd' is used only with 'fd', or the correspondign plural) then libvirt should be able to use this unconditionally, right?
Even for the case when you pass queues > 0, you can't provide vhostfds but only vhostfd (and QEMU will try to reuse it for all queues, which (as I understand) is a bug in current QEMU.
Okay I'm not sure how this works and if it has implications on libvirt. Specifically we don't seem to be ever passing 'queues' to -netdev in conjunction with fd/vhostfd or the correspondive plurals. Specifically 'queues' are only used with 'vhost-user' and 'vhost-vdpa' types, where fd/vhostfd or the plurals are not used. If the above is safe to use only with 1 fd used in the plural options then libvirt should be safe. Regardless of that if 'queues' *can* be used with this config but has such implications as you claim it IMO should be documented too in the deprecation document.
On 30.01.26 17:17, Peter Krempa wrote:
On Fri, Jan 30, 2026 at 15:23:37 +0300, Vladimir Sementsov-Ogievskiy wrote:
On 30.01.26 14:44, Peter Krempa wrote:
On Fri, Jan 30, 2026 at 00:53:38 +0300, Vladimir Sementsov-Ogievskiy wrote:
They are the same as fds and vhostfds, except they accept only one fd. Let's deprecate redundant options.
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> ---
Hi all!
after "[PATCH v2 00/12] net: refactoring and fixes" options fd and vhostfd becomes redundant, fds and vhostfds may be used instead.
this patch also based on "[PATCH v6] qapi: net: deprecate vhostforce option", that's why it's sent separately.
Based-on: <20260129213215.1405459-1-vsementsov@yandex-team.ru> Based-on: <20251113071711.349651-1-vsementsov@yandex-team.ru>
docs/about/deprecated.rst | 6 ++++++ qapi/net.json | 9 +++++---- 2 files changed, 11 insertions(+), 4 deletions(-)
diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst index e8ff478583..9010f8ab07 100644 --- a/docs/about/deprecated.rst +++ b/docs/about/deprecated.rst @@ -451,6 +451,12 @@ TAP ``vhostforce`` (since 11.0) The ``vhostforce`` option is redundant with the ``vhost`` option. If they conflict, ``vhost`` takes precedence. Just use ``vhost``. +TAP ``fd`` and ``vhostfd`` (since 11.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``fds`` and ``vhostfds`` correspondingly, each set with one fd +instead of ``fd`` and ``vhsotfd``.
Does this replacement apply/work on all versions supporting vhostfds/fd?
I'm asking because libvirt does have code to format the singlular vs plural but none of the versions we support are lacking support for the plural forms so we could replace this unconditionally if it works with older versions.
Unfortunately, before "[PATCH v2 00/12] net: refactoring and fixes", some things will not work, if use fds/vhostfds instead of fd/vhostfd for one-queue TAP. Still, probably these cases are not used in Libvirt?
In that case any caveats should IMO be documented in the deprecation document.
Will add.
for one-queue TAP. Still, probably these cases are not used in Libvirt?
Note that the network stuff in libvirt isn't my specialization so I might be missing stuff that was not metioned explicitly.
1. Prior the series, tap.c code has check:
/* QEMU hubs do not support multiqueue tap, in this case peer is set. * For -netdev, peer is always NULL. */ if (peer && (tap->has_queues || tap->fds || tap->vhostfds)) { error_setg(errp, "Multiqueue tap cannot be used with hubs"); return -1; }
So if that comment is accurate we only use fd/vhostfd with -netdev so this won't trigger in libvirt.
This is too restrictive: obviously queues may be set to 1, and fds/vhostfds may contain only one FD, but QEMU doesn't check it.
So, this case require fd/vhostfd options, if you want to pass some fds.
What this "hub" actually is? As I can see, it's -net cmdline option except for nic:
static int net_client_init1(const Netdev *netdev, bool is_netdev, Error **errp) { ... /* Do not add to a hub if it's a nic with a netdev= parameter. */ if (netdev->type != NET_CLIENT_DRIVER_NIC || !netdev->u.nic.netdev) { peer = net_hub_add_port(0, NULL, NULL); } ... }
2. Prior the series, you may pass vhostfds only together with fds. If you want to pass vhostfd for cases without fds, you have to use only vhostfd option.
So in the test data we seem to be using vhostfd only with fd (or the crresponding plural form) but I'm not 100% sure based on the fact that the formatters for the option are conditional on whether the FDs were opened first.
The code opening the FDs seems to open 'vhostfd' only when 'fd' are populated.
So if the above is the case (as in 'vhostfd' is used only with 'fd', or the correspondign plural) then libvirt should be able to use this unconditionally, right?
Yes, if I didn't miss something. I'll double check.
Even for the case when you pass queues > 0, you can't provide vhostfds but only vhostfd (and QEMU will try to reuse it for all queues, which (as I understand) is a bug in current QEMU.
Okay I'm not sure how this works and if it has implications on libvirt.
Specifically we don't seem to be ever passing 'queues' to -netdev in conjunction with fd/vhostfd or the correspondive plurals.
That's correct fd=, fds= and queues= are mutual exclusive. Still, vhostfd may be used withuot fd.. But that's rather strange.
Specifically 'queues' are only used with 'vhost-user' and 'vhost-vdpa' types, where fd/vhostfd or the plurals are not used.
If the above is safe to use only with 1 fd used in the plural options then libvirt should be safe.
Regardless of that if 'queues' *can* be used with this config but has such implications as you claim it IMO should be documented too in the deprecation document.
Agree, I'll add the necessary documentation -- Best regards, Vladimir
On Sun, Feb 01, 2026 at 18:08:52 +0300, Vladimir Sementsov-Ogievskiy wrote:
On 30.01.26 17:17, Peter Krempa wrote:
On Fri, Jan 30, 2026 at 15:23:37 +0300, Vladimir Sementsov-Ogievskiy wrote:
On 30.01.26 14:44, Peter Krempa wrote:
On Fri, Jan 30, 2026 at 00:53:38 +0300, Vladimir Sementsov-Ogievskiy wrote:
They are the same as fds and vhostfds, except they accept only one fd. Let's deprecate redundant options.
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> ---
Hi all!
after "[PATCH v2 00/12] net: refactoring and fixes" options fd and vhostfd becomes redundant, fds and vhostfds may be used instead.
this patch also based on "[PATCH v6] qapi: net: deprecate vhostforce option", that's why it's sent separately.
Based-on: <20260129213215.1405459-1-vsementsov@yandex-team.ru> Based-on: <20251113071711.349651-1-vsementsov@yandex-team.ru>
docs/about/deprecated.rst | 6 ++++++ qapi/net.json | 9 +++++---- 2 files changed, 11 insertions(+), 4 deletions(-)
diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst index e8ff478583..9010f8ab07 100644 --- a/docs/about/deprecated.rst +++ b/docs/about/deprecated.rst @@ -451,6 +451,12 @@ TAP ``vhostforce`` (since 11.0) The ``vhostforce`` option is redundant with the ``vhost`` option. If they conflict, ``vhost`` takes precedence. Just use ``vhost``. +TAP ``fd`` and ``vhostfd`` (since 11.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``fds`` and ``vhostfds`` correspondingly, each set with one fd +instead of ``fd`` and ``vhsotfd``.
Does this replacement apply/work on all versions supporting vhostfds/fd?
I'm asking because libvirt does have code to format the singlular vs plural but none of the versions we support are lacking support for the plural forms so we could replace this unconditionally if it works with older versions.
Unfortunately, before "[PATCH v2 00/12] net: refactoring and fixes", some things will not work, if use fds/vhostfds instead of fd/vhostfd for one-queue TAP. Still, probably these cases are not used in Libvirt?
In that case any caveats should IMO be documented in the deprecation document.
Will add.
for one-queue TAP. Still, probably these cases are not used in Libvirt?
Note that the network stuff in libvirt isn't my specialization so I might be missing stuff that was not metioned explicitly.
1. Prior the series, tap.c code has check:
/* QEMU hubs do not support multiqueue tap, in this case peer is set. * For -netdev, peer is always NULL. */ if (peer && (tap->has_queues || tap->fds || tap->vhostfds)) { error_setg(errp, "Multiqueue tap cannot be used with hubs"); return -1; }
So if that comment is accurate we only use fd/vhostfd with -netdev so this won't trigger in libvirt.
This is too restrictive: obviously queues may be set to 1, and fds/vhostfds may contain only one FD, but QEMU doesn't check it.
So, this case require fd/vhostfd options, if you want to pass some fds.
What this "hub" actually is? As I can see, it's -net cmdline option except for nic:
static int net_client_init1(const Netdev *netdev, bool is_netdev, Error **errp) { ... /* Do not add to a hub if it's a nic with a netdev= parameter. */ if (netdev->type != NET_CLIENT_DRIVER_NIC || !netdev->u.nic.netdev) { peer = net_hub_add_port(0, NULL, NULL); } ... }
2. Prior the series, you may pass vhostfds only together with fds. If you want to pass vhostfd for cases without fds, you have to use only vhostfd option.
So in the test data we seem to be using vhostfd only with fd (or the crresponding plural form) but I'm not 100% sure based on the fact that the formatters for the option are conditional on whether the FDs were opened first.
The code opening the FDs seems to open 'vhostfd' only when 'fd' are populated.
So if the above is the case (as in 'vhostfd' is used only with 'fd', or the correspondign plural) then libvirt should be able to use this unconditionally, right?
Yes, if I didn't miss something. I'll double check.
So since the deprecation will break libvirt's test code once it's commited and libvirt updates capability dumps I've proposed two patchsets: Variant A: https://lists.libvirt.org/archives/list/devel@lists.libvirt.org/message/USXO... Variant B: https://lists.libvirt.org/archives/list/devel@lists.libvirt.org/message/QMIV... Variant A is the simpler approach of just unconditionally switching to the plural variants which *should* work based on the above, but is out of my specialization to verify it properly. I've thus also proposed the more cautious variant B which adds a capability which detects that the singular spelling is deprecated and swtiches to the plural only when that is the case.
Even for the case when you pass queues > 0, you can't provide vhostfds but only vhostfd (and QEMU will try to reuse it for all queues, which (as I understand) is a bug in current QEMU.
Okay I'm not sure how this works and if it has implications on libvirt.
Specifically we don't seem to be ever passing 'queues' to -netdev in conjunction with fd/vhostfd or the correspondive plurals.
That's correct fd=, fds= and queues= are mutual exclusive. Still, vhostfd may be used withuot fd.. But that's rather strange.
Hi Markus, On 1/29/26 1:53 PM, Vladimir Sementsov-Ogievskiy wrote:
They are the same as fds and vhostfds, except they accept only one fd. Let's deprecate redundant options.
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> ---
Hi all!
after "[PATCH v2 00/12] net: refactoring and fixes" options fd and vhostfd becomes redundant, fds and vhostfds may be used instead.
this patch also based on "[PATCH v6] qapi: net: deprecate vhostforce option", that's why it's sent separately.
Based-on: <20260129213215.1405459-1-vsementsov@yandex-team.ru> Based-on: <20251113071711.349651-1-vsementsov@yandex-team.ru>
docs/about/deprecated.rst | 6 ++++++ qapi/net.json | 9 +++++---- 2 files changed, 11 insertions(+), 4 deletions(-)
I'll let you pull this, including doc changes, in case you're ok with the series. Regards, Pierrick
participants (3)
-
Peter Krempa -
Pierrick Bouvier -
Vladimir Sementsov-Ogievskiy