qemu-doc: update deprecation section to use -nic and -netdev hubport

The deprecated SLIRP options -tftp, -bootp, -redir, -smb provide
sample replacements that use "-net nic".  Suggest "-nic" instead,
since we finally have a path towards getting rid of "-net".

For "-net vlan" the replacement involves hubport network devices,
so mention that too.

Cc: Thomas Huth <thuth@redhat.com>
Cc: Jason Wang <jasowang@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 qemu-doc.texi | 38 +++++++++++++++++++++-----------------
 1 file changed, 21 insertions(+), 17 deletions(-)

On 07.03.2018 15:28, Paolo Bonzini wrote:
> The deprecated SLIRP options -tftp, -bootp, -redir, -smb provide
> sample replacements that use "-net nic".  Suggest "-nic" instead,
> since we finally have a path towards getting rid of "-net".
> 
> For "-net vlan" the replacement involves hubport network devices,
> so mention that too.
> 
> Cc: Thomas Huth <thuth@redhat.com>
> Cc: Jason Wang <jasowang@redhat.com>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
>  qemu-doc.texi | 38 +++++++++++++++++++++-----------------
>  1 file changed, 21 insertions(+), 17 deletions(-)
> 
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 39e38c87ec..918d97c18b 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -2643,42 +2643,46 @@ combined with ``-vnc tls-creds=tls0'
>  
>  @subsection -tftp (since 2.6.0)
>  
> -The ``-tftp /some/dir'' argument is replaced by
> -``-netdev user,id=x,tftp=/some/dir'', either accompanied with
> -``-device ...,netdev=x'' (for pluggable NICs) or ``-net nic,netdev=x''
> +The ``-tftp /some/dir'' argument is replaced by either
> +``-netdev user,id=x,tftp=/some/dir '' (for pluggable NICs, accompanied
> +with ``-device ...,netdev=x''), or ``-nic user,tftp=/some/dir''
>  (for embedded NICs). The new syntax allows different settings to be
>  provided per NIC.
>  
>  @subsection -bootp (since 2.6.0)
>  
> -The ``-bootp /some/file'' argument is replaced by
> -``-netdev user,id=x,bootp=/some/file'', either accompanied with
> -``-device ...,netdev=x'' (for pluggable NICs) or ``-net nic,netdev=x''
> +The ``-bootp /some/file'' argument is replaced by either
> +``-netdev user,id=x,bootp=/some/file '' (for pluggable NICs, accompanied
> +with ``-device ...,netdev=x''), or ``-nic user,bootp=/some/file''
>  (for embedded NICs). The new syntax allows different settings to be
>  provided per NIC.
>  
>  @subsection -redir (since 2.6.0)
>  
>  The ``-redir [tcp|udp]:hostport:[guestaddr]:guestport'' argument is
> -replaced by ``-netdev
> -user,id=x,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport'',
> -either accompanied with ``-device ...,netdev=x'' (for pluggable NICs) or
> -``-net nic,netdev=x'' (for embedded NICs). The new syntax allows different
> -settings to be provided per NIC.
> +replaced by either
> +``-netdev user,id=x,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport''
> +(for pluggable NICs, accompanied with ``-device ...,netdev=x'') or
> +``-nic user,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport''
> +(for embedded NICs). The new syntax allows different settings to be
> +provided per NIC.
>  
>  @subsection -smb (since 2.6.0)
>  
> -The ``-smb /some/dir'' argument is replaced by
> -``-netdev user,id=x,smb=/some/dir'', either accompanied with
> -``-device ...,netdev=x'' (for pluggable NICs) or ``-net nic,netdev=x''
> +The ``-smb /some/dir'' argument is replaced by either
> +``-netdev user,id=x,smb=/some/dir '' (for pluggable NICs, accompanied
> +with ``-device ...,netdev=x''), or ``-nic user,smb=/some/dir''
>  (for embedded NICs). The new syntax allows different settings to be
>  provided per NIC.
>  
>  @subsection -net vlan (since 2.9.0)
>  
> -The ``-net vlan=NN'' argument is partially replaced with the
> -new ``-netdev'' argument. The remaining use cases will no
> -longer be directly supported in QEMU.
> +The ``-net vlan=NN'' argument was mostly used to attach separate
> +network backends to different virtual NICs.  This is the default
> +behavior for ``-netdev'' and ``-nic''.  You can connect multiple
> +``-netdev'' and ``-nic'' devices to the same network using the
> +"hubport" network backend, created with ``-netdev hubport,hubid=NN,...''
> +and ``-nic hubport,hubid=NN''.
>  
>  @subsection -drive cyls=...,heads=...,secs=...,trans=... (since 2.10.0)

Acked-by: Thomas Huth <thuth@redhat.com>

But please note that we've currently got a BiteSizeTask to replace all
single-dash options with double dash options here:

https://wiki.qemu.org/BiteSizedTasks#Consistent_option_usage_in_documentation

So it would be nicer if you'd directly use double dash options here now.
(Note that you also got to use @option{--nic xxx} instead of ``--nic xxx''
in that case)

 Thomas

On 07/03/2018 15:38, Thomas Huth wrote:
> But please note that we've currently got a BiteSizeTask to replace all
> single-dash options with double dash options here:
> 
> https://wiki.qemu.org/BiteSizedTasks#Consistent_option_usage_in_documentation

Is anybody actually using VLANs^Wdouble dash options?  I learnt about
them a month ago...

Paolo

> So it would be nicer if you'd directly use double dash options here now.
> (Note that you also got to use @option{--nic xxx} instead of ``--nic xxx''
> in that case)

On 07.03.2018 15:43, Paolo Bonzini wrote:
> On 07/03/2018 15:38, Thomas Huth wrote:
>> But please note that we've currently got a BiteSizeTask to replace all
>> single-dash options with double dash options here:
>>
>> https://wiki.qemu.org/BiteSizedTasks#Consistent_option_usage_in_documentation
> 
> Is anybody actually using VLANs^Wdouble dash options?  I learnt about
> them a month ago...

I use them accidentally now and then ... but I think the BiteSizeTask
description has a point: We're really very inconsistent between QEMU
itself and the tools like qemu-img... So I think that task is basically
a good idea.

 Thomas