Re: [PATCH 2/2] qemu-options.hx: Improve -serial option documentation

[Philippe Mathieu-Daudé]

Hi,

On 22/1/24 17:36, Peter Maydell wrote:
> The -serial option documentation is a bit brief about '-serial none'
> and '-serial null'. In particular it's not very clear about the
> difference between them, and it doesn't mention that it's up to
> the machine model whether '-serial none' means "don't create the
> serial port" or "don't wire the serial port up to anything".
>
> Expand on these points.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>   qemu-options.hx | 14 +++++++++++---
>   1 file changed, 11 insertions(+), 3 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index ced82848637..d8c3fe91de1 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -4129,7 +4129,8 @@ SRST
>       This option can be used several times to simulate up to 4 serial
>       ports.
>   
> -    Use ``-serial none`` to disable all serial ports.
> +    You can use ``-serial none`` to suppress the creation of default
> +    serial devices.
>   
>       Available character devices are:
>   
> @@ -4151,10 +4152,17 @@ SRST
>           [Linux only] Pseudo TTY (a new PTY is automatically allocated)
>   
>       ``none``
> -        No device is allocated.
> +        No device is allocated. Note that 

>          for machine types which
> +        emulate systems where a serial device is always present in
> +        real hardware, this may be equivalent to the ``null`` option,
> +        in that the serial device is still present but all output
> +        is discarded.

Should we deprecate this broken case, suggesting to use ``null``
instead?

>          For boards where the number of serial ports is
> +        truly variable, this suppresses the creation of the device.
>   
>       ``null``
> -        void device
> +        A guest will see the UART or serial device as present in the
> +        machine, but all output is discarded, and there is no input.
> +        Conceptually equivalent to redirecting the output to ``/dev/null``.
>   
>       ``chardev:id``
>           Use a named character device defined with the ``-chardev``

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>