Re: [Qemu-devel] [PATCH v2] doc: document -netdev hubport

[Stefan Hajnoczi]

On Fri, Feb 22, 2013 at 10:54:47AM +0100, Markus Armbruster wrote:
> Stefan Hajnoczi <address@hidden> writes:
> 
> > On Thu, Feb 21, 2013 at 03:17:51PM +0100, Markus Armbruster wrote:
> >> Stefan Hajnoczi <address@hidden> writes:
> >> 
> >> > Signed-off-by: Stefan Hajnoczi <address@hidden>
> >> > ---
> >> >  qemu-options.hx | 11 ++++++++++-
> >> >  1 file changed, 10 insertions(+), 1 deletion(-)
> >> >
> >> > diff --git a/qemu-options.hx b/qemu-options.hx
> >> > index 4bc9c85..cd18ad1 100644
> >> > --- a/qemu-options.hx
> >> > +++ b/qemu-options.hx
> >> > @@ -1404,7 +1404,8 @@ DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
> >> >  #ifdef CONFIG_VDE
> >> >      "vde|"
> >> >  #endif
> >> > -    "socket],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
> >> > +    "socket|"
> >> > +    "hubport],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
> >> >  STEXI
> >> >  @item -net nic[,address@hidden,address@hidden,address@hidden 
> >> > [,address@hidden,address@hidden,address@hidden
> >> >  @findex -net
> >> > @@ -1726,6 +1727,14 @@ vde_switch -F -sock /tmp/myswitch
> >> >  qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
> >> >  @end example
> >> >  
> >> > address@hidden -netdev hubport,address@hidden,address@hidden
> >> > +
> >> > +Create a hub port on QEMU "vlan" @var{hubid}.  This syntax is an 
> >> > alternative to
> >> > +the @code{-net @option{vlan}} argument and can be used to connect a NIC
> >> > +specified with @code{-device ...,address@hidden to a QEMU "vlan".
> >> 
> >> A simpler way to use a "vlan" with -device is "-device e1000,vlan=0".
> >> How is that related to hubport?
> >
> > That is yet another shortcut syntax.  It does the same thing as -netdev
> > hubport,id=tmphubport0,hubid=0 -device e1000,netdev=tmphubport0.
> 
> Perhaps documentation should point to the shorthand syntax.  Let me try:
> 
>     Create a hub port on QEMU "vlan" @var{hubid}.
> 
>     The hubport netdev lets you connect a NIC to a QEMU "vlan" instead
>     of a single netdev.  @code{-net} and @code{-device} with parameter
>     @option{vlan} create the required hub automatically.

Your version is easier to read.  Works fine by me.

> >> > +
> >> > +Note that only NICs can be connected to a hubport, other -netdevs 
> >> > cannot.
> >> > +
> >> 
> >> Well, netdevs can't be connected to a netdev in general, and hubport is
> >> one.  You can connect up to one device model to a netdev.  I figure you
> >> can additionally connect any number of old-style -net thingies to it,
> >> whether they are NICs or not.  Correct?
> >
> > net.c doesn't stop NetClients from connecting to each other.  It's just
> > our -netdev option parsing code which doesn't allow -netdevs to connect
> > with each other.
> >
> > -net instances can only connect to hub ports.
> 
> I find the note confusing.  "Only NICs" suggests only NICs can connect,
> which isn't true; one NIC and any number of "vlan" clients (defined with
> -net) can connect.  The fact that the code would happily connect
> arbitrary netdevs is of no interest to the user.  Drop the note?

I was trying to express that -netdev hubport -netdev slirp cannot be
used together, only -netdev hubport -device virtio-net-pci.  In other
words, -netdev hubport only works with -device <NIC>.

Let's drop the note.

I'll send a v3.

Stefan