Re: [Qemu-devel] [PATCH v2 8/8] qemu-doc: Make "-net" less prominent

[Paolo Bonzini]

On 21/02/2018 01:05, Thomas Huth wrote:
> On 20.02.2018 19:37, Paolo Bonzini wrote:
>> On 20/02/2018 18:40, Thomas Huth wrote:
>>> "-net" is clearly a legacy option. Yet we still use it in almost all
>>> examples in the qemu documentation, and many other spots in the network
>>> chapter. We should make it less prominent that users are not lured into
>>> using it so often anymore. So instead of starting the network chapter with
>>> "-net nic" and documenting "-net " below "-netdev "
>>> everywhere, all the "-net" related documentation is now moved to the end
>>> of the chapter. And the examples are changed to use the "--device" and
>>> "--netdev" options instead of "-net nic -net ".
>>
>> Do we want to change them to "-nic" instead?  The proof is in the
>> pudding, they say, :) and "-nic" is way easier to learn than "-device
>> -netdev".
> 
> While -nic is easier to use than -netdev, I don't think that we should
> put the focus in our main qemu-doc on -nic instead of -netdev. -nic is a
> convenience option, while -netdev is the "architected" way to configure
> network devices. We first should document how to do it "right", and
> teach the user to proper distinguish between emulated guest hardware and
> host network backend (with the old -net command, a lot of people seemed
> to have mixed that up IIRC), and then finally explain -nic on top of it.

Heh, that's a philosophy question regarding the organization of the
whole manual.  Currently the "architected" way is pretty much confined
to docs/qdev-device-use.txt.  The manual is full of uses of -drive or
-hda, and I think it makes sense because honestly that's what users use.
 I should have explained this in the previous message, sorry.

>> And maybe we *should* go the extra mile and deprecate "-net" altogether.
>>  The only case where the newer syntax is a bit more uncomfortable is for
>> "-net nic -net nic -net tap|user", which however does work with "-nic
>> hubport -nic hubport -netdev tap|user,id=x -netdev hubport,netdev=x".
> 
> I'd be glad to add such a deprecation patch to this series - I just
> thought it might have been too early so far, but if you feel confident
> that we can mark it as deprecated, I can spin a v3 with such a patch on
> top...

I can't deny it's going to be a lng deprecation.  But we have to
start somewhere, and -nic is a great start.

I think you should send v3 with the minimal changes required to accept
these patches, and then leave the rest to a separate submission, but of
course you don't have to do it that way.

Thanks,

Paolo

Re: [Qemu-devel] [PATCH v2 8/8] qemu-doc: Make "-net" less prominent

[Thomas Huth]

On 20.02.2018 19:37, Paolo Bonzini wrote:
> On 20/02/2018 18:40, Thomas Huth wrote:
>> "-net" is clearly a legacy option. Yet we still use it in almost all
>> examples in the qemu documentation, and many other spots in the network
>> chapter. We should make it less prominent that users are not lured into
>> using it so often anymore. So instead of starting the network chapter with
>> "-net nic" and documenting "-net " below "-netdev "
>> everywhere, all the "-net" related documentation is now moved to the end
>> of the chapter. And the examples are changed to use the "--device" and
>> "--netdev" options instead of "-net nic -net ".
> 
> Do we want to change them to "-nic" instead?  The proof is in the
> pudding, they say, :) and "-nic" is way easier to learn than "-device
> -netdev".

While -nic is easier to use than -netdev, I don't think that we should
put the focus in our main qemu-doc on -nic instead of -netdev. -nic is a
convenience option, while -netdev is the "architected" way to configure
network devices. We first should document how to do it "right", and
teach the user to proper distinguish between emulated guest hardware and
host network backend (with the old -net command, a lot of people seemed
to have mixed that up IIRC), and then finally explain -nic on top of it.

> And maybe we *should* go the extra mile and deprecate "-net" altogether.
>  The only case where the newer syntax is a bit more uncomfortable is for
> "-net nic -net nic -net tap|user", which however does work with "-nic
> hubport -nic hubport -netdev tap|user,id=x -netdev hubport,netdev=x".

I'd be glad to add such a deprecation patch to this series - I just
thought it might have been too early so far, but if you feel confident
that we can mark it as deprecated, I can spin a v3 with such a patch on
top...

 Thomas

Re: [Qemu-devel] [PATCH v2 8/8] qemu-doc: Make "-net" less prominent

[Paolo Bonzini]

On 20/02/2018 18:40, Thomas Huth wrote:
> "-net" is clearly a legacy option. Yet we still use it in almost all
> examples in the qemu documentation, and many other spots in the network
> chapter. We should make it less prominent that users are not lured into
> using it so often anymore. So instead of starting the network chapter with
> "-net nic" and documenting "-net " below "-netdev "
> everywhere, all the "-net" related documentation is now moved to the end
> of the chapter. And the examples are changed to use the "--device" and
> "--netdev" options instead of "-net nic -net ".

Do we want to change them to "-nic" instead?  The proof is in the
pudding, they say, :) and "-nic" is way easier to learn than "-device
-netdev".

And maybe we *should* go the extra mile and deprecate "-net" altogether.
 The only case where the newer syntax is a bit more uncomfortable is for
"-net nic -net nic -net tap|user", which however does work with "-nic
hubport -nic hubport -netdev tap|user,id=x -netdev hubport,netdev=x".

For now I suggest dropping this patch.

Paolo

[Qemu-devel] [PATCH v2 8/8] qemu-doc: Make "-net" less prominent

[Thomas Huth]

"-net" is clearly a legacy option. Yet we still use it in almost all
examples in the qemu documentation, and many other spots in the network
chapter. We should make it less prominent that users are not lured into
using it so often anymore. So instead of starting the network chapter with
"-net nic" and documenting "-net " below "-netdev "
everywhere, all the "-net" related documentation is now moved to the end
of the chapter. And the examples are changed to use the "--device" and
"--netdev" options instead of "-net nic -net ".

Signed-off-by: Thomas Huth 
---
 qemu-options.hx | 176 +++-
 1 file changed, 86 insertions(+), 90 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 399905e..ff5da07 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2048,41 +2048,18 @@ DEF("net", HAS_ARG, QEMU_OPTION_net,
 "old way to initialize a host network interface\n"
 "(use the -netdev option if possible instead)\n", 
QEMU_ARCH_ALL)
 STEXI
-@item -net 
nic[,vlan=@var{n}][,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] 
[,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
-@findex -net
-Configure or create an on-board (or machine default) Network Interface Card
-(NIC) and connect it either to VLAN @var{n} (@var{n} = 0 is the default), or
-to the netdev @var{nd}. The NIC is an e1000 by default on the PC
-target. Optionally, the MAC address can be changed to @var{mac}, the
-device address set to @var{addr} (PCI cards only),
-and a @var{name} can be assigned for use in monitor commands.
-Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
-that the card should have; this option currently only affects virtio cards; set
-@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
-NIC is created.  QEMU can emulate several different models of network card.
-Valid values for @var{type} are
-@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
-@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
-@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.
-
-@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
-@findex -netdev
-@item -net user[,@var{option}][,@var{option}][,...]
-Use the user mode network stack which requires no administrator
+@item --netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
+@findex --netdev
+Configure user mode host network backend which requires no administrator
 privilege to run. Valid options are:
 
 @table @option
-@item vlan=@var{n}
-Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
-
 @item id=@var{id}
-@itemx name=@var{name}
 Assign symbolic name for use in monitor commands.
 
-@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must
-be enabled.  If neither is specified both protocols are enabled.
+@item ipv4=on|off and ipv6=on|off
+Specify that either IPv4 or IPv6 must be enabled. If neither is specified
+both protocols are enabled.
 
 @item net=@var{addr}[/@var{mask}]
 Set IP network address the guest will see. Optionally specify the netmask,
@@ -2134,7 +2111,7 @@ can not be resolved.
 
 Example:
 @example
-qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
+qemu-system-i386 --device e1000,netdev=n1 --netdev 
user,id=n1,dnssearch=mgmt.example.org,dnssearch=example.org [...]
 @end example
 
 @item tftp=@var{dir}
@@ -2150,7 +2127,8 @@ a guest from a local directory.
 
 Example (using pxelinux):
 @example
-qemu-system-i386 -hda linux.img -boot n -net 
user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
+qemu-system-i386 --hda linux.img --boot n --device e1000,netdev=n1 \
+--netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
 @end example
 
 @item smb=@var{dir}[,smbserver=@var{addr}]
@@ -2185,7 +2163,7 @@ screen 0, use the following:
 
 @example
 # on the host
-qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
+qemu-system-i386 --device virtio-net-pci,netdev=n1 --netdev 
user,id=n1,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
 # this host xterm should open in the guest X11 server
 xterm -display :1
 @end example
@@ -2195,7 +2173,7 @@ the guest, use the following:
 
 @example
 # on the host
-qemu-system-i386 -net user,hostfwd=tcp::-:23 [...]
+qemu-system-i386 --device e1000,netdev=n1 --netdev 
user,id=n1,hostfwd=tcp::-:23 [...]
 telnet localhost 
 @end example
 
@@ -2214,7 +2192,7 @@ lifetime, like in the following example:
 @example
 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
 # the guest accesses it
-qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
+qemu-system-i386 --device e1000,netdev=n1 --netdev 
user,id=n1,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
 @end example
 
 Or you can execute a