[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH] net: Change help text to list -netdev instead o
From: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] [PATCH] net: Change help text to list -netdev instead of -net by default |
Date: |
Fri, 08 May 2015 14:44:51 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) |
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.