[v2] doc: document -netdev hubport

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 qemu-options.hx | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

Stefan Hajnoczi <stefanha@redhat.com> writes:

> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  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[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
>  @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
>  
> +@item -netdev hubport,id=@var{id},hubid=@var{hubid}
> +
> +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 ...,netdev=@var{id}} to a QEMU "vlan".

A simpler way to use a "vlan" with -device is "-device e1000,vlan=0".
How is that related to hubport?

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

>  @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
>  Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
>  At most @var{len} bytes (64k by default) per packet are stored. The file format is

I'm afraid you missed netdev_add in hmp-command.hx.

On Thu, Feb 21, 2013 at 03:17:51PM +0100, Markus Armbruster wrote:
> Stefan Hajnoczi <stefanha@redhat.com> writes:
> 
> > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> > ---
> >  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[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
> >  @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
> >  
> > +@item -netdev hubport,id=@var{id},hubid=@var{hubid}
> > +
> > +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 ...,netdev=@var{id}} 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.

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

> >  @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
> >  Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
> >  At most @var{len} bytes (64k by default) per packet are stored. The file format is
> 
> I'm afraid you missed netdev_add in hmp-command.hx.

Thanks, will fix.

Stefan Hajnoczi <stefanha@redhat.com> writes:

> On Thu, Feb 21, 2013 at 03:17:51PM +0100, Markus Armbruster wrote:
>> Stefan Hajnoczi <stefanha@redhat.com> writes:
>> 
>> > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
>> > ---
>> >  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[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
>> >  @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
>> >  
>> > +@item -netdev hubport,id=@var{id},hubid=@var{hubid}
>> > +
>> > +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 ...,netdev=@var{id}} 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.

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

[...]

On Fri, Feb 22, 2013 at 10:54:47AM +0100, Markus Armbruster wrote:
> Stefan Hajnoczi <stefanha@redhat.com> writes:
> 
> > On Thu, Feb 21, 2013 at 03:17:51PM +0100, Markus Armbruster wrote:
> >> Stefan Hajnoczi <stefanha@redhat.com> writes:
> >> 
> >> > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> >> > ---
> >> >  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[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
> >> >  @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
> >> >  
> >> > +@item -netdev hubport,id=@var{id},hubid=@var{hubid}
> >> > +
> >> > +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 ...,netdev=@var{id}} 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