[PATCH 0/4] qapi/net: Some doc improvement and cleanup

[PATCH 0/4] qapi/net: Some doc improvement and cleanup

[Markus Armbruster]

This series replaces useless documentation by hopefully useful one.
I'm not familiar with this stuff, though.  Please review critically.

Markus Armbruster (4):
  qapi/net: Rename NetDevPasstOptions to NetdevPasstOptions
  qapi/net: Wean passt off QAPI type String to improve documentation
  qapi/net: Wean SLIRP off QAPI type String to improve documentation
  qapi/net: Drop unused type String

 qapi/net.json | 96 ++++++++++++++++++++++++++++++++++++++++++++-------
 net/passt.c   | 10 +++---
 net/slirp.c   | 27 +++++++++++----
 3 files changed, 109 insertions(+), 24 deletions(-)

-- 
2.54.0

[PATCH 1/4] qapi/net: Rename NetDevPasstOptions to NetdevPasstOptions

[Markus Armbruster]

We have eighteen QAPI type names starting with Netdev.  Commit
854ee02b222 (net: Add passt network backend) added a first one
starting with NetDev.  Rename it for consistency.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/net.json | 6 +++---
 net/passt.c   | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/qapi/net.json b/qapi/net.json
index 118bd34965..8ed51b665c 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -115,7 +115,7 @@
     'str': 'str' } }
 
 ##
-# @NetDevPasstOptions:
+# @NetdevPasstOptions:
 #
 # Unprivileged user-mode network connectivity using passt
 #
@@ -191,7 +191,7 @@
 #
 # Since: 10.1
 ##
-{ 'struct': 'NetDevPasstOptions',
+{ 'struct': 'NetdevPasstOptions',
   'data': {
     '*path':               'str',
     '*quiet':              'bool',
@@ -877,7 +877,7 @@
   'discriminator': 'type',
   'data': {
     'nic':      'NetLegacyNicOptions',
-    'passt':    { 'type': 'NetDevPasstOptions',
+    'passt':    { 'type': 'NetdevPasstOptions',
                   'if': 'CONFIG_PASST' },
     'user':     'NetdevUserOptions',
     'tap':      'NetdevTapOptions',
diff --git a/net/passt.c b/net/passt.c
index 4ff94ee509..f1f59d50c4 100644
--- a/net/passt.c
+++ b/net/passt.c
@@ -499,7 +499,7 @@ static int net_passt_vhost_user_init(NetPasstState *s, Error **errp)
 }
 #endif
 
-static GPtrArray *net_passt_decode_args(const NetDevPasstOptions *passt,
+static GPtrArray *net_passt_decode_args(const NetdevPasstOptions *passt,
                                         gchar *pidfile, Error **errp)
 {
     GPtrArray *args = g_ptr_array_new_with_free_func(g_free);
-- 
2.54.0

[PATCH 2/4] qapi/net: Wean passt off QAPI type String to improve documentation

[Markus Armbruster]

String's doc comment is useless.  Replace its use in
NetDevPasstOptions by identical types with hopefully useful
documentation.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/net.json | 43 +++++++++++++++++++++++++++++++++++++++----
 net/passt.c   |  8 ++++----
 2 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/qapi/net.json b/qapi/net.json
index 8ed51b665c..45ee7ac7ff 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -114,6 +114,41 @@
   'data': {
     'str': 'str' } }
 
+##
+# @PasstSearch:
+#
+# @str: DNS domain name suffix for host name lookup, or "none".  See
+#     passt(1) option --search.
+#
+# Since: 1.2
+##
+{ 'struct': 'PasstSearch',
+  'data': {
+    'str': 'str' } }
+
+##
+# @PasstPortForward:
+#
+# @str: passt port forwarding specification, see passt(1) option
+#     --tcp-ports and --udp-ports.
+#
+# Since: 10.1
+##
+{ 'struct': 'PasstPortForward',
+  'data': {
+    'str': 'str' } }
+
+##
+# @PasstParameter:
+#
+# @str: Additional arguments for the passt executable, see passt(1)
+#
+# Since: 10.1
+##
+{ 'struct': 'PasstParameter',
+  'data': {
+    'str': 'str' } }
+
 ##
 # @NetdevPasstOptions:
 #
@@ -206,7 +241,7 @@
     '*outbound-if4':       'str',
     '*outbound-if6':       'str',
     '*dns':                'str',
-    '*search':             ['String'],
+    '*search':             ['PasstSearch'],
     '*fqdn':               'str',
     '*dhcp-dns':           'bool',
     '*dhcp-search':        'bool',
@@ -224,9 +259,9 @@
     '*freebind':           'bool',
     '*ipv4':               'bool',
     '*ipv6':               'bool',
-    '*tcp-ports':          ['String'],
-    '*udp-ports':          ['String'],
-    '*param':             ['String'] },
+    '*tcp-ports':          ['PasstPortForward'],
+    '*udp-ports':          ['PasstPortForward'],
+    '*param':              ['PasstParameter'] },
     'if': 'CONFIG_PASST' }
 
 ##
diff --git a/net/passt.c b/net/passt.c
index f1f59d50c4..53e0a4f444 100644
--- a/net/passt.c
+++ b/net/passt.c
@@ -641,7 +641,7 @@ static GPtrArray *net_passt_decode_args(const NetdevPasstOptions *passt,
     }
 
     if (passt->has_search && passt->search) {
-        const StringList *list = passt->search;
+        const PasstSearchList *list = passt->search;
         GString *domains = g_string_new(list->value->str);
 
         list = list->next;
@@ -656,7 +656,7 @@ static GPtrArray *net_passt_decode_args(const NetdevPasstOptions *passt,
     }
 
     if (passt->has_tcp_ports && passt->tcp_ports) {
-        const StringList *list = passt->tcp_ports;
+        const PasstPortForwardList *list = passt->tcp_ports;
         GString *tcp_ports = g_string_new(list->value->str);
 
         list = list->next;
@@ -671,7 +671,7 @@ static GPtrArray *net_passt_decode_args(const NetdevPasstOptions *passt,
     }
 
     if (passt->has_udp_ports && passt->udp_ports) {
-        const StringList *list = passt->udp_ports;
+        const PasstPortForwardList *list = passt->udp_ports;
         GString *udp_ports = g_string_new(list->value->str);
 
         list = list->next;
@@ -686,7 +686,7 @@ static GPtrArray *net_passt_decode_args(const NetdevPasstOptions *passt,
     }
 
     if (passt->has_param && passt->param) {
-        const StringList *list = passt->param;
+        const PasstParameterList *list = passt->param;
 
         while (list) {
             g_ptr_array_add(args, g_strdup(list->value->str));
-- 
2.54.0

[PATCH 3/4] qapi/net: Wean SLIRP off QAPI type String to improve documentation

[Markus Armbruster]

String's doc comment is useless.  Replace its use in NetdevUserOptions
by identical types with hopefully useful documentation.

While there, add a non-doc commment explaining why the port forwarding
interface is problematic.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/net.json | 52 ++++++++++++++++++++++++++++++++++++++++++++++++---
 net/slirp.c   | 27 ++++++++++++++++++++------
 2 files changed, 70 insertions(+), 9 deletions(-)

diff --git a/qapi/net.json b/qapi/net.json
index 45ee7ac7ff..aabf116d16 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -264,6 +264,52 @@
     '*param':              ['PasstParameter'] },
     'if': 'CONFIG_PASST' }
 
+##
+# @NetdevUserDomainSuffix:
+#
+# @str: DNS domain name suffix for host name lookup, similar to
+#     resolv.conf(5)
+#
+# Since: 1.2
+##
+{ 'struct': 'NetdevUserDomainSuffix',
+  'data': {
+    'str': 'str' } }
+
+##
+# @NetdevUserHostForward:
+#
+# @str: Host port forwarding rule
+#
+# TODO: This string gets parsed by slirp_hostfwd().  We fail to
+#    document syntax and semantics here.  We do in qemu-options.hx.
+#    Parsing structured configuration from strings is a no-no for QMP.
+#    This should really be a struct.  Not sure it's worth the bother
+#    now.
+#
+# Since: 1.2
+##
+{ 'struct': 'NetdevUserHostForward',
+  'data': {
+    'str': 'str' } }
+
+##
+# @NetdevUserGuestForward:
+#
+# @str: Guest port forwarding rule
+#
+# TODO: This string gets parsed by slirp_guestfwd().  We fail to
+#    document syntax and semantics here.  We do in qemu-options.hx.
+#    Parsing structured configuration from strings is a no-no for QMP.
+#    This should really be a struct.  Not sure it's worth the bother
+#    now.
+#
+# Since: 1.2
+##
+{ 'struct': 'NetdevUserGuestForward',
+  'data': {
+    'str': 'str' } }
+
 ##
 # @NetdevUserOptions:
 #
@@ -340,7 +386,7 @@
     '*bootfile':  'str',
     '*dhcpstart': 'str',
     '*dns':       'str',
-    '*dnssearch': ['String'],
+    '*dnssearch': ['NetdevUserDomainSuffix'],
     '*domainname': 'str',
     '*ipv6-prefix':      'str',
     '*ipv6-prefixlen':   'int',
@@ -348,8 +394,8 @@
     '*ipv6-dns':         'str',
     '*smb':       'str',
     '*smbserver': 'str',
-    '*hostfwd':   ['String'],
-    '*guestfwd':  ['String'],
+    '*hostfwd':   ['NetdevUserHostForward'],
+    '*guestfwd':  ['NetdevUserGuestForward'],
     '*tftp-server-name': 'str' } }
 
 ##
diff --git a/net/slirp.c b/net/slirp.c
index 04925f3318..a00e0a9651 100644
--- a/net/slirp.c
+++ b/net/slirp.c
@@ -1215,14 +1215,14 @@ void hmp_info_usernet(Monitor *mon, const QDict *qdict)
 }
 
 static void
-net_init_slirp_configs(const StringList *fwd, int flags)
+net_init_slirp_configs_host(const NetdevUserHostForwardList *fwd)
 {
     while (fwd) {
         struct slirp_config_str *config;
 
         config = g_malloc0(sizeof(*config));
         pstrcpy(config->str, sizeof(config->str), fwd->value->str);
-        config->flags = flags;
+        config->flags = SLIRP_CFG_HOSTFWD;
         config->next = slirp_configs;
         slirp_configs = config;
 
@@ -1230,9 +1230,24 @@ net_init_slirp_configs(const StringList *fwd, int flags)
     }
 }
 
-static const char **slirp_dnssearch(const StringList *dnsname)
+static void
+net_init_slirp_configs_guest(const NetdevUserGuestForwardList *fwd)
 {
-    const StringList *c = dnsname;
+    while (fwd) {
+        struct slirp_config_str *config;
+
+        config = g_malloc0(sizeof(*config));
+        pstrcpy(config->str, sizeof(config->str), fwd->value->str);
+        config->next = slirp_configs;
+        slirp_configs = config;
+
+        fwd = fwd->next;
+    }
+}
+
+static const char **slirp_dnssearch(const NetdevUserDomainSuffixList *dnsname)
+{
+    const NetdevUserDomainSuffixList *c = dnsname;
     size_t i = 0, num_opts = 0;
     const char **ret;
 
@@ -1285,8 +1300,8 @@ int net_init_slirp(const Netdev *netdev, const char *name,
 
     /* all optional fields are initialized to "all bits zero" */
 
-    net_init_slirp_configs(user->hostfwd, SLIRP_CFG_HOSTFWD);
-    net_init_slirp_configs(user->guestfwd, 0);
+    net_init_slirp_configs_host(user->hostfwd);
+    net_init_slirp_configs_guest(user->guestfwd);
 
     ret = net_slirp_init(peer, "user", name, user->q_restrict,
                          ipv4, vnet, user->host,
-- 
2.54.0

[PATCH 4/4] qapi/net: Drop unused type String

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/net.json | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/qapi/net.json b/qapi/net.json
index aabf116d16..7dcda6009c 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -103,17 +103,6 @@
     '*addr':    'str',
     '*vectors': 'uint32' } }
 
-##
-# @String:
-#
-# A fat type wrapping 'str', to be embedded in lists.
-#
-# Since: 1.2
-##
-{ 'struct': 'String',
-  'data': {
-    'str': 'str' } }
-
 ##
 # @PasstSearch:
 #
-- 
2.54.0

Re: [PATCH 0/4] qapi/net: Some doc improvement and cleanup

[marcandre.lureau]

On Wed, 06 May 2026 12:54:17 +0200, Markus Armbruster <armbru@redhat.com> wrote:
> qapi/net: Some doc improvement and cleanup
> 
> This series replaces useless documentation by hopefully useful one.
> I'm not familiar with this stuff, though.  Please review critically.
> 
> Markus Armbruster (4):
>   qapi/net: Rename NetDevPasstOptions to NetdevPasstOptions
>   qapi/net: Wean passt off QAPI type String to improve documentation
>   qapi/net: Wean SLIRP off QAPI type String to improve documentation
>   qapi/net: Drop unused type String
> 
> [...]

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>

-- 
Marc-André Lureau <marcandre.lureau@redhat.com>

Re: [PATCH 3/4] qapi/net: Wean SLIRP off QAPI type String to improve documentation

[marcandre.lureau]

On Wed, 06 May 2026 12:54:20 +0200, Markus Armbruster <armbru@redhat.com> wrote:
> String's doc comment is useless.  Replace its use in NetdevUserOptions
> by identical types with hopefully useful documentation.
> 
> While there, add a non-doc commment explaining why the port forwarding
> interface is problematic.

commment -> comment

-- 
Marc-André Lureau <marcandre.lureau@redhat.com>

Re: [PATCH 2/4] qapi/net: Wean passt off QAPI type String to improve documentation

[marcandre.lureau]

On Wed, 06 May 2026 12:54:19 +0200, Markus Armbruster <armbru@redhat.com> wrote:
> diff --git a/qapi/net.json b/qapi/net.json
> index 8ed51b665cd..45ee7ac7ffc 100644
> --- a/qapi/net.json
> +++ b/qapi/net.json
> @@ -114,6 +114,41 @@
>    'data': {
>      'str': 'str' } }
>  
> +##
> +# @PasstSearch:
> +#
> +# @str: DNS domain name suffix for host name lookup, or "none".  See
> +#     passt(1) option --search.
> +#
> +# Since: 1.2

Since 10.1

-- 
Marc-André Lureau <marcandre.lureau@redhat.com>

Re: [PATCH 2/4] qapi/net: Wean passt off QAPI type String to improve documentation

[Markus Armbruster]

marcandre.lureau@redhat.com writes:

> On Wed, 06 May 2026 12:54:19 +0200, Markus Armbruster <armbru@redhat.com> wrote:
>> diff --git a/qapi/net.json b/qapi/net.json
>> index 8ed51b665cd..45ee7ac7ffc 100644
>> --- a/qapi/net.json
>> +++ b/qapi/net.json
>> @@ -114,6 +114,41 @@
>>    'data': {
>>      'str': 'str' } }
>>  
>> +##
>> +# @PasstSearch:
>> +#
>> +# @str: DNS domain name suffix for host name lookup, or "none".  See
>> +#     passt(1) option --search.
>> +#
>> +# Since: 1.2
>
> Since 10.1

Yes.  I score 2 of 3 points.

Thank you!

Re: [PATCH 3/4] qapi/net: Wean SLIRP off QAPI type String to improve documentation

[Markus Armbruster]

marcandre.lureau@redhat.com writes:

> On Wed, 06 May 2026 12:54:20 +0200, Markus Armbruster <armbru@redhat.com> wrote:
>> String's doc comment is useless.  Replace its use in NetdevUserOptions
>> by identical types with hopefully useful documentation.
>> 
>> While there, add a non-doc commment explaining why the port forwarding
>> interface is problematic.
>
> commment -> comment

Fixed, thanks!

Re: [PATCH 0/4] qapi/net: Some doc improvement and cleanup

[Markus Armbruster]

Markus Armbruster <armbru@redhat.com> writes:

> This series replaces useless documentation by hopefully useful one.
> I'm not familiar with this stuff, though.  Please review critically.

Queued.