net: Change help text to list -netdev instead of -net by default

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 <[email protected]>

---
 qemu-options.hx | 66 ++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 39 insertions(+), 27 deletions(-)

qemu-options.hx +1 -4

index ec356f6..2cab5f3 100644
@@ -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"

qemu-options.hx +9 -9

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

qemu-options.hx +2 -3

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

Quoted 9 lines · 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.

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.

qemu-options.hx DEF("net", HAS_ARG, QEMU_OPTION_net, · line 1499

Quoted 10 lines

" (default=" DEFAULT_BRIDGE_INTERFACE ") using the program 'helper'\n"
" (default=" DEFAULT_BRIDGE_HELPER ")\n"
#endif
#ifdef __linux__

qemu-options.hx +4 -1

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

Quoted 15 lines

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

qemu-options.hx +2 -3

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

qemu-options.hx DEF("netdev", HAS_ARG, QEMU_OPTION_netdev, · line 1566

Quoted 6 lines

qemu-options.hx +3 -3

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

Quoted 7 lines

qemu-options.hx +2 -0

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

qemu-options.hx Valid values for @var{type} are · line 1589

Quoted 2 lines

qemu-options.hx +0 -0

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

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 <[email protected]>

---
 qemu-options.hx | 66 ++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 39 insertions(+), 27 deletions(-)

Quoted 10 lines · 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.

Quoted 4 lines

Signed-off-by Thomas Huth <[email protected]>

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