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

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

[Thomas Huth]

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.

Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 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"
 #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"
 #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"
     "                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"
     "                (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"
     "                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"
     "-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)
 STEXI
 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
 @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
+@code{-device @var{type},netdev=@var{id}} option instead.
 
 @item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
 @findex -netdev
-- 
1.8.3.1

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

[Markus Armbruster]

Thomas Huth <thuth@redhat.com> 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 <thuth@redhat.com>
> ---
>  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[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
>  @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
> +@code{-device @var{type},netdev=@var{id}} option instead.
>  
>  @item -netdev user,id=@var{id}[,@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.

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

[Paolo Bonzini]

On 08/05/2015 11:36, Thomas Huth wrote:
> 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.
> 
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>  qemu-options.hx | 66 ++++++++++++++++++++++++++++++++++-----------------------
>  1 file changed, 39 insertions(+), 27 deletions(-)

That would be great if it worked for all machine types, but it doesn't.
 For example, there's no equivalent of:

$ qemu-system-arm -net user -net nic -machine versatilepb

You cannot just use -netdev:

$ qemu-system-arm -netdev user,id=nd0 -machine versatilepb
Warning: netdev nd0 has no peer

You cannot use -netdev and -net together:

$ qemu-system-arm -netdev user,id=nd0 -net nic -machine versatilepb
Warning: vlan 0 is not connected to host network
Warning: netdev nd0 has no peer

This particular board has a PCI controller, so you can just add a PCI
NIC using -netdev/-device, but still that wouldn't be a match for "-net
user -net nic" (which puts a smc91c111 NIC on sysbus).  In most embedded
boards there's not even a PCI controller.

So the patch is great, but I wouldn't say it's deprecated, because in
practice it isn't.

Paolo

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

[Thomas Huth]

On Fri, 08 May 2015 14:44:51 +0200
Markus Armbruster <armbru@redhat.com> wrote:

> Thomas Huth <thuth@redhat.com> 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.

Thanks for the review, most of your suggestions look really fine, will
include them in the next version of the patch!

[...]
> >      "                (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*"?

Ah, missed to update that string ...

> What about:
> 
>                 configure a network backend with ID 'str'
>                 connected to an Ethernet over L2TPv3 pseudowire

... and this sounds better of course.

> 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.

Ack, will update.

> >      "-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?

I would not include this in the output of -help. -help is just for
getting a quick look at the syntax and not for getting full
documentation, I think. Such a hint should go into the normal doc files
instead (and there you already can see the options side by side).


> > @@ -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
> > +@code{-device @var{type},netdev=@var{id}} option instead.
> >  
> >  @item -netdev user,id=@var{id}[,@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.

Ok, here the options are normally listed side by side already. It's
just the "-net nic" option that still sits at the top. But I can move
that to the end of the section too, if you like.

 Thomas

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

[Thomas Huth]

On Fri, 08 May 2015 16:39:49 +0200
Paolo Bonzini <pbonzini@redhat.com> wrote:

> 
> 
> On 08/05/2015 11:36, Thomas Huth wrote:
> > 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.
> > 
> > Signed-off-by: Thomas Huth <thuth@redhat.com>
> > ---
> >  qemu-options.hx | 66 ++++++++++++++++++++++++++++++++++-----------------------
> >  1 file changed, 39 insertions(+), 27 deletions(-)
> 
> That would be great if it worked for all machine types, but it doesn't.
>  For example, there's no equivalent of:
> 
> $ qemu-system-arm -net user -net nic -machine versatilepb
> 
> You cannot just use -netdev:
> 
> $ qemu-system-arm -netdev user,id=nd0 -machine versatilepb
> Warning: netdev nd0 has no peer
> 
> You cannot use -netdev and -net together:
> 
> $ qemu-system-arm -netdev user,id=nd0 -net nic -machine versatilepb
> Warning: vlan 0 is not connected to host network
> Warning: netdev nd0 has no peer
> 
> This particular board has a PCI controller, so you can just add a PCI
> NIC using -netdev/-device, but still that wouldn't be a match for "-net
> user -net nic" (which puts a smc91c111 NIC on sysbus).  In most embedded
> boards there's not even a PCI controller.
> 
> So the patch is great, but I wouldn't say it's deprecated, because in
> practice it isn't.

Ok, makes sense, I'll remove the "deprecated" wording.

 Thomas