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

[Peter Maydell <peter.maydell@linaro.org>]

On Mon, 22 Jan 2024 at 17:46, Philippe Mathieu-Daudé <philmd@linaro.org> wrote:
>
> 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?

It's machine specific. On systems with pluggable serial devices
it makes sense to use '-serial none' to get rid of them
entirely. On systems where the UARTs are hardwired into the
board, having '-serial none' literally delete the UART device
just breaks guests, which is why those boards make it behave
like '-serial null'. But users should still be able to use
'-serial none' to say "I don't really care about serial here".

(This is why in commit 12051d82f004024d5d we made the chardev
frontend functions cope with having a NULL backend, to avoid
boards having to say "oh, serial_hd(n) is NULL, I must create
a 'null' backend for it", which half of them didn't do.)

thanks
-- PMM