Re: [Qemu-devel] [PATCH v3] qemu-doc: Rework the network options chapter to make "-net" less prominent

[Thomas Huth <thuth@redhat.com>]

On 27.03.2018 15:01, Jason Wang wrote:
> 
> 
> On 2018年03月12日 20:20, 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 <backend>" below "-netdev <backend>"
>> everywhere, all the "-net" related documentation is now moved to the end
>> of the chapter. The new "-nic" option is moved to the beginning of the
>> chapter instead, with a new example that should demonstrate how "-nic"
>> can be used to shortcut "-device" with "-netdev". The examples in this
>> chapter are changed to use the "-device" and "-netdev" options or
>> "-nic" instead of "-net nic -net <backend>".
>>
>> While we're at it, also remove a legacy remark about very old Linux
>> distributions. Also remove the "[...]" from the examples in this chapter
>> since we are not using this ellipsis in any other examples in our docu-
>> mentation.
>>
>> Signed-off-by: Thomas Huth <thuth@redhat.com>
>> ---
>>   v3:
>>   - Use single dash options instead of double-dash options
>>
>>   qemu-options.hx | 189
>> ++++++++++++++++++++++++++++----------------------------
>>   1 file changed, 94 insertions(+), 95 deletions(-)
>>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index 6585058..e86b3fb 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
[...]
>> +@item -nic
>> [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
>>
>> +@findex -nic
>> +This option is a shortcut for configuring both the on-board (default)
>> guest
>> +NIC hardware and the host network backend in one go. The host backend
>> options
>> +are the same as with the corresponding @option{-netdev} options below.
>> +The guest NIC model can be set with @option{model=@var{modelname}}.
>> +Use @option{model=help} to list the available device types.
>> +The hardware MAC address can be set with @option{mac=@var{macaddr}}.
>> +
>> +The following two example do exactly the same, to show how
>> @option{-nic} can
>> +be used to shorten the command line length (note that the e1000 is
>> the default
>> +on i386, so the @option{model=e1000} parameter could even be omitted
>> here, too):
>> +@example
>> +qemu-system-i386 -netdev user,id=n1,ipv6=off -device
>> e1000,netdev=n1,mac=52:54:98:76:54:32
>> +qemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
>> +@end example
> 
> I'm not sure we need this since I believe we still prefer -netdev even
> if -nic is shorter?

[...]
>> @@ -2443,19 +2433,9 @@ Example:
>>   # launch vde switch
>>   vde_switch -F -sock /tmp/myswitch
>>   # launch QEMU instance
>> -qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
>> +qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch
> 
> I think we should use -netdev here?

I've had that in the original version of this patch, but Paolo suggested
to use -nic instead since this is more "user-friendly":

https://lists.gnu.org/archive/html/qemu-devel/2018-02/msg05258.html

I personally don't mind whether we use "-netdev" or "-nic" in the
examples, as long as we finally get rid of "-net" there... Please let me
know which way you prefer, so I can respin the patch again if necessary.

 Thomas