Re: [PATCH v14 06/17] qapi: net: add stream and dgram netdevs

[Alex Bennée <alex.bennee@xxxxxxxxxx>]

Laurent Vivier <lvivier@xxxxxxxxxx> writes:

> Copied from socket netdev file and modified to use SocketAddress
> to be able to introduce new features like unix socket.
>
<snip>
> index eb38e5dc40bc..396c1d11e1e2 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2772,6 +2772,18 @@ DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
>      "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
>      "                configure a network backend to connect to another 
> network\n"
>      "                using an UDP tunnel\n"
> +    "-netdev 
> stream,id=str[,server=on|off],addr.type=inet,addr.host=host,addr.port=port\n"
> +    "-netdev 
> stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor\n"
> +    "                configure a network backend to connect to another 
> network\n"
> +    "                using a socket connection in stream mode.\n"
> +    "-netdev 
> dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=inet,local.host=addr]\n"
> +    "-netdev 
> dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=fd,local.str=file-descriptor]\n"
> +    "                configure a network backend to connect to a multicast 
> maddr and port\n"
> +    "                use ``local.host=addr`` to specify the host address to 
> send packets from\n"
> +    "-netdev 
> dgram,id=str,local.type=inet,local.host=addr,local.port=port[,remote.type=inet,remote.host=addr,remote.port=port]\n"
> +    "-netdev dgram,id=str,local.type=fd,local.str=file-descriptor\n"
> +    "                configure a network backend to connect to another 
> network\n"
> +    "                using an UDP tunnel\n"
>  #ifdef CONFIG_VDE
>      "-netdev 
> vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
>      "                configure a network backend to connect to port 'n' of a 
> vde switch\n"

While the option documentation is good it might be worth taking some
additional time to document the wider networking stack. It is a topic
that often sees confusion amongst users and is a complex area of
functionality.

At a minimum a bit of preamble around DEFHEADING(Network option:) to
explain how devices and backends interact might help users understand
the context for the individual options themselves before launching
directly into explaining each one.

We also have some stuff on the wiki:

  https://wiki.qemu.org/Documentation/Networking
  https://wiki.qemu.org/Documentation/Networking/NAT

that might be worth sanitising and transcribing into a section of the
system emulation manual. We can then point to :ref:`networking` in the
options documentation so the user doesn't have to piece together
disparate bits of online information themselves.

-- 
Alex Bennée