Re: [PATCH v7 4/4] qemu-options.hx: describe hub chardev and aggregation of several backends

[Roman Penyaev]

On Tue, Jan 21, 2025 at 4:23 PM Roman Penyaev <r.peniaev@gmail.com> wrote:
>
> On Tue, Jan 21, 2025 at 4:02 PM Alex Bennée <alex.bennee@linaro.org> wrote:
> >
> > Roman Penyaev <r.peniaev@gmail.com> writes:
> >
> > > This adds a few lines describing `hub` aggregator configuration
> > > for aggregation of several backend devices with a single frontend
> > > device.
> > >
> > > Signed-off-by: Roman Penyaev <r.peniaev@gmail.com>
> > > Cc: "Marc-André Lureau" <marcandre.lureau@redhat.com>
> > > Cc: qemu-devel@nongnu.org
> > > ---
> > >  qemu-options.hx | 48 ++++++++++++++++++++++++++++++++++++++++++++----
> > >  1 file changed, 44 insertions(+), 4 deletions(-)
> > >
> > > diff --git a/qemu-options.hx b/qemu-options.hx
> > > index 7090d59f6f10..fdc46f7e68b3 100644
> > > --- a/qemu-options.hx
> > > +++ b/qemu-options.hx
> > > @@ -3720,7 +3720,7 @@ SRST
> > >  The general form of a character device option is:
> > >
> > >  ``-chardev backend,id=id[,mux=on|off][,options]``
> > > -    Backend is one of: ``null``, ``socket``, ``udp``, ``msmouse``,
> > > +    Backend is one of: ``null``, ``socket``, ``udp``, ``msmouse``, 
> > > ``hub``,
> > >      ``vc``, ``ringbuf``, ``file``, ``pipe``, ``console``, ``serial``,
> > >      ``pty``, ``stdio``, ``braille``, ``parallel``,
> > >      ``spicevmc``, ``spiceport``. The specific backend will determine the
> > > @@ -3777,9 +3777,10 @@ The general form of a character device option is:
> > >      the QEMU monitor, and ``-nographic`` also multiplexes the console
> > >      and the monitor to stdio.
> > >
> > > -    There is currently no support for multiplexing in the other
> > > -    direction (where a single QEMU front end takes input and output from
> > > -    multiple chardevs).
> > > +    If you need to aggregate data in the opposite direction (where one
> > > +    QEMU frontend interface receives input and output from multiple
> > > +    backend chardev devices), please refer to the paragraph below
> > > +    regarding chardev ``hub`` aggregator device configuration.
> > >
> > >      Every backend supports the ``logfile`` option, which supplies the
> > >      path to a file to record all data transmitted via the backend. The
> > > @@ -3879,6 +3880,45 @@ The available backends are:
> > >      Forward QEMU's emulated msmouse events to the guest. ``msmouse``
> > >      does not take any options.
> > >
> > > +``-chardev hub,id=id,chardevs.0=id[,chardevs.N=id]`` Explicitly create
> > > +    chardev backend hub device with the possibility to aggregate input
> > > +    from multiple backend devices and forward it to a single frontend
> > > +    device. Additionally, `hub` device takes the output from the
> > > +    frontend device and sends it back to all the connected backend
> > > +    devices. This allows for seamless interaction between different
> > > +    backend devices and a single frontend interface. Aggregation
> > > +    supported for up to 4 chardev devices. (Since 10.0)
> > > +
> > > +    For example, the following is a use case of 2 backend devices:
> > > +    virtual console ``vc0`` and a pseudo TTY ``pty0`` connected to
> > > +    a single virtio hvc console frontend device with a hub ``hub0``
> > > +    help. Virtual console renders text to an image, which can be
> > > +    shared over the VNC protocol. In turn, pty backend provides
> > > +    bidirectional communication to the virtio hvc console over the
> > > +    pseudo TTY file. The example configuration can be as follows:
> > > +
> > > +    ::
> > > +
> > > +       -chardev pty,path=/tmp/pty,id=pty0 \
> > > +       -chardev vc,id=vc0 \
> > > +       -chardev hub,id=hub0,chardevs.0=pty0,chardevs.1=vc0 \
> > > +       -device virtconsole,chardev=hub0 \
> > > +       -vnc 0.0.0.0:0
> > > +
> > > +    Once QEMU starts VNC client and any TTY emulator can be used to
> > > +    control a single hvc console:
> > > +
> > > +    ::
> > > +
> > > +       # Start TTY emulator
> > > +       tio /tmp/pty
> > > +
> > > +       # Start VNC client and switch to virtual console Ctrl-Alt-2
> > > +       vncviewer :0
> > > +
> > > +    Several frontend devices is not supported. Stacking of multiplexers
> > > +    and hub devices is not supported as well.
> > > +
> >
> > Not sure why this breaks but I'm seeing:
> >
> >   FAILED: docs/docs.stamp
> >   /usr/bin/env CONFDIR=etc/qemu 
> > /home/alex/lsrc/qemu.git/builds/all/pyvenv/bin/sphinx-build -q -W 
> > -Dkerneldoc_werror=1 -j auto -Dversion=9.2.50 -Drelease= 
> > -Ddepfile=docs/docs.d -Ddepfile_stamp=docs/docs.stamp -b html -d 
> > /home/alex/lsrc/qemu.git/builds/all/docs/manual.p 
> > /home/alex/lsrc/qemu.git/docs 
> > /home/alex/lsrc/qemu.git/builds/all/docs/manual
> >
> >   Warning, treated as error:
> >   /home/alex/lsrc/qemu.git/qemu-options.hx:3884:'any' reference target not 
> > found: hub
>
> This is odd, my make is silent. Can you please check this?

Docs generation was disabled on my side. My bad. The problem is in the
`hub`, which should be ``hub``. Thanks for noticing that.

--
Roman