Re: [Qemu-devel] [PATCH] net: Change help text to list -netdev instead of -net by default

[Markus Armbruster]

Thomas Huth <address@hidden> writes:

> Looking at the output of "qemu-system-xxx -help", you easily get
> the impression that "-net" is the preferred way instead of "-netdev"
> to specify host network interface, since the "-net" option is
> omnipresent but the "-netdev" option is only listed as a one-liner
> at the end. This is ugly since "-net" is considered as legacy and
> even might be removed one day. Thus, this patch switches the output
> to explain the host network interfaces with the "-netdev" option
> instead, moving the legacy "-net" option into some few lines at
> the end.

Thanks a lot for tackling this!

I'm only superficially familiar with this stuff, but that's not a bad
thing for reviewing help, so here goes.

>
> Signed-off-by: Thomas Huth <address@hidden>
> ---
>  qemu-options.hx | 66 
> ++++++++++++++++++++++++++++++++++-----------------------
>  1 file changed, 39 insertions(+), 27 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index ec356f6..2cab5f3 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1449,25 +1449,25 @@ DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", 
> QEMU_ARCH_ALL)
>  #endif
>  #endif
>  
> -DEF("net", HAS_ARG, QEMU_OPTION_net,
> -    "-net 
> nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
> -    "                create a new Network Interface Card and connect it to 
> VLAN 'n'\n"
> +DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
>  #ifdef CONFIG_SLIRP
> -    "-net 
> user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=on|off]\n"
> +    "-netdev user,id=str[,net=addr[/mask]][,host=addr][,restrict=on|off]\n"
>      "         
> [,hostname=host][,dhcpstart=addr][,dns=addr][,dnssearch=domain][,tftp=dir]\n"
>      "         [,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
>  #ifndef _WIN32
>                                               "[,smb=dir[,smbserver=addr]]\n"
>  #endif
> -    "                connect the user mode network stack to VLAN 'n', 
> configure its\n"
> -    "                DHCP server and enabled optional services\n"
> +    "                enable a user mode network interface, identified by 
> 'str',\n"
> +    "                configure its DHCP server and enabled optional 
> services\n"

Suggest

                configure a user mode network backend with ID 'str',
                its DHCP server and optional services

>  #endif
>  #ifdef _WIN32
> -    "-net tap[,vlan=n][,name=str],ifname=name\n"
> -    "                connect the host TAP network interface to VLAN 'n'\n"
> +    "-netdev tap,id=str,ifname=name\n"
> +    "                enable a host TAP network interface with ID 'str'\n"

Suggest

                configure a host TAP network backend with ID 'str'

>  #else
> -    "-net 
> tap[,vlan=n][,name=str][,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
> -    "                connect the host TAP network interface to VLAN 'n'\n"
> +    "-netdev 
> tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
> +    "         
> [,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
> +    "         
> [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
> +    "                enable a host TAP network interface, identified by 
> 'str'\n"

Same help line as for _WIN32, please.

>      "                use network scripts 'file' (default=" 
> DEFAULT_NETWORK_SCRIPT ")\n"
>      "                to configure it and 'dfile' (default=" 
> DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
>      "                to deconfigure it\n"
> @@ -1486,13 +1486,16 @@ DEF("net", HAS_ARG, QEMU_OPTION_net,
>      "                use 'vhostfd=h' to connect to an already opened vhost 
> net device\n"
>      "                use 'vhostfds=x:y:...:z to connect to multiple already 
> opened vhost net devices\n"
>      "                use 'queues=n' to specify the number of queues to be 
> created for multiqueue TAP\n"
> -    "-net bridge[,vlan=n][,name=str][,br=bridge][,helper=helper]\n"
> +    "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
>      "                connects a host TAP network interface to a host bridge 
> device 'br'\n"

I'm not sure I understand this help, either before or after the patch.
Reading commit a7c36ee... okay, this seems to be shorthand for -net
tap,helper=.../qemu-bridge-helper.  What about:

                configure a host TAP network backend with ID 'str'
                that is connected to a bridge

>      "                (default=" DEFAULT_BRIDGE_INTERFACE ") using the 
> program 'helper'\n"
>      "                (default=" DEFAULT_BRIDGE_HELPER ")\n"
>  #endif
>  #ifdef __linux__
> -    "-net 
> l2tpv3[,vlan=n][,name=str],src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6=on/off][,udp=on/off][,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]\n"
> +    "-netdev 
> l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
> +    "         
> [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
> +    "         
> [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
> +    "         [,rxcookie=rxcookie][,offset=offset]\n"
>      "                connect the VLAN to an Ethernet over L2TPv3 
> pseudowire\n"

"connect the *VLAN*"?

What about:

                configure a network backend with ID 'str'
                connected to an Ethernet over L2TPv3 pseudowire

I'm sure you get the idea by now: help always starts with something like
"configure a [FOO] network backend with ID 'str' [connected thusly].
Nice and regular.

More of the same below.

>      "                Linux kernel 3.3+ as well as most routers can talk\n"
>      "                L2TPv3. This transport allows connecting a VM to a 
> VM,\n"
> @@ -1514,32 +1517,39 @@ DEF("net", HAS_ARG, QEMU_OPTION_net,
>      "                use 'pincounter=on' to work around broken counter 
> handling in peer\n"
>      "                use 'offset=X' to add an extra offset between header 
> and data\n"
>  #endif
> -    "-net 
> socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
> -    "                connect the vlan 'n' to another VLAN using a socket 
> connection\n"
> -    "-net 
> socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
> -    "                connect the vlan 'n' to multicast maddr and port\n"
> +    "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
> +    "                connect the network to another network using a socket 
> connection\n"
> +    "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
> +    "                connect the network to multicast maddr and port\n"
>      "                use 'localaddr=addr' to specify the host address to 
> send packets from\n"
> -    "-net 
> socket[,vlan=n][,name=str][,fd=h][,udp=host:port][,localaddr=host:port]\n"
> -    "                connect the vlan 'n' to another VLAN using an UDP 
> tunnel\n"
> +    "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
> +    "                connect the network to another network using an UDP 
> tunnel\n"
>  #ifdef CONFIG_VDE
> -    "-net 
> vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
> -    "                connect the vlan 'n' to port 'n' of a vde switch 
> running\n"
> +    "-netdev 
> vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
> +    "                connect the network to port 'n' of a vde switch 
> running\n"
>      "                on host and listening for incoming connections on 
> 'socketpath'.\n"
>      "                Use group 'groupname' and mode 'octalmode' to change 
> default\n"
>      "                ownership and permissions for communication port.\n"
>  #endif
>  #ifdef CONFIG_NETMAP
> -    "-net netmap,ifname=name[,devname=nmname]\n"
> +    "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
>      "                attach to the existing netmap-enabled network interface 
> 'name', or to a\n"
>      "                VALE port (created on the fly) called 'name' ('nmname' 
> is name of the \n"
>      "                netmap device, defaults to '/dev/netmap')\n"
>  #endif
> +    "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
> +    "                establish a vhost-user netdev, backed by a chardev 
> 'dev'\n"
> +    "-netdev hubport,id=str,hubid=n\n"
> +    "                Create a hub port on QEMU VLAN 'n'\n", QEMU_ARCH_ALL)
> +DEF("net", HAS_ARG, QEMU_OPTION_net,
> +    "-net 
> nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
> +    "                deprecated way to create a new NIC and connect it to 
> VLAN 'n'\n"
> +    "                (note: use the '-device type,netdev=str' option 
> instead)\n"

Suggests -device TYPE,... works when -net nic,model=TYPE does.
Counter-example: -net nic,model=virtio,... -> -device virtio-net,...

What about:

                (use -device driver,netdev=str,... instead)

Same issue in STEXI..ETEXI below.

>      "-net dump[,vlan=n][,file=f][,len=n]\n"
>      "                dump traffic on vlan 'n' to file 'f' (max n bytes per 
> packet)\n"
>      "-net none       use it alone to have zero network devices. If no -net 
> option\n"
> -    "                is provided, the default is '-net nic -net user'\n", 
> QEMU_ARCH_ALL)
> -DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
> -    "-netdev ["
> +    "                is provided, the default is '-net nic -net user'\n"
> +    "-net ["
>  #ifdef CONFIG_SLIRP
>      "user|"
>  #endif
> @@ -1551,9 +1561,9 @@ DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
>  #ifdef CONFIG_NETMAP
>      "netmap|"
>  #endif
> -    "vhost-user|"
> -    "socket|"
> -    "hubport],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
> +    "socket][,vlan=n][,option][,option][,...]\n"
> +    "                Deprecated way to initialize a host network interface\n"
> +    "                (use -netdev instead)\n", QEMU_ARCH_ALL)

Should we add a hint on how to translate -net to -netdev?

>  STEXI
>  @item -net nic[,address@hidden,address@hidden,address@hidden 
> [,address@hidden,address@hidden,address@hidden
>  @findex -net
> @@ -1572,6 +1582,8 @@ Valid values for @var{type} are
>  @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
>  Not all devices are supported on all targets.  Use @code{-net nic,model=help}
>  for a list of available devices for your target.
> +Note that this option is deprecated, NICs should be created with the
> address@hidden @var{type},address@hidden option instead.
>  
>  @item -netdev user,address@hidden,@var{option}][,@var{option}][,...]
>  @findex -netdev

The hunks above rearranged -help to show -netdev before -net.  You could
do the same for the documentation in STEXI..ETEXI.  But the patch is
valuable even without it.