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

["Alex Bennée" <alex.bennee@linaro.org>]

Roman Penyaev <r.peniaev@gmail.com> writes:

> 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?
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index fdc46f7e68b3..e6d9de142aaf 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -3880,7 +3880,8 @@ 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 hub,id=id,chardevs.0=id[,chardevs.N=id]``
> +    Explicitly create

No joy. I did replicate from the command line and s/-q/-v/

  writing output... [ 43%] specs/fsi .. specs/ppc-spapr-hotplug

  Traceback (most recent call last):
    File "/usr/lib/python3/dist-packages/sphinx/cmd/build.py", line 281, in build_main
      app.build(args.force_all, args.filenames)
    File "/usr/lib/python3/dist-packages/sphinx/application.py", line 341, in build
      self.builder.build_update()
    File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 310, in build_update
      self.build(to_build,
    File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 376, in build
      self.write(docnames, list(updated_docnames), method)
    File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 568, in write
      self._write_parallel(sorted(docnames),
    File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 612, in _write_parallel
      doctree = self.env.get_and_resolve_doctree(docname, self)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    File "/usr/lib/python3/dist-packages/sphinx/environment/__init__.py", line 591, in get_and_resolve_doctree
      self.apply_post_transforms(doctree, docname)
    File "/usr/lib/python3/dist-packages/sphinx/environment/__init__.py", line 637, in apply_post_transforms
      transformer.apply_transforms()
    File "/usr/lib/python3/dist-packages/sphinx/transforms/__init__.py", line 80, in apply_transforms
      super().apply_transforms()
    File "/usr/lib/python3/dist-packages/docutils/transforms/__init__.py", line 173, in apply_transforms
      transform.apply(**kwargs)
    File "/usr/lib/python3/dist-packages/sphinx/transforms/post_transforms/__init__.py", line 35, in apply
      self.run(**kwargs)
    File "/usr/lib/python3/dist-packages/sphinx/transforms/post_transforms/__init__.py", line 97, in run
      self.warn_missing_reference(refdoc, typ, target, node, domain)
    File "/usr/lib/python3/dist-packages/sphinx/transforms/post_transforms/__init__.py", line 204, in warn_missing_reference
      logger.warning(msg, location=node, type='ref', subtype=typ)
    File "/usr/lib/python3.11/logging/__init__.py", line 1855, in warning
      self.log(WARNING, msg, *args, **kwargs)
    File "/usr/lib/python3/dist-packages/sphinx/util/logging.py", line 123, in log
      super().log(level, msg, *args, **kwargs)
    File "/usr/lib/python3.11/logging/__init__.py", line 1887, in log
      self.logger.log(level, msg, *args, **kwargs)
    File "/usr/lib/python3.11/logging/__init__.py", line 1559, in log
      self._log(level, msg, args, **kwargs)
    File "/usr/lib/python3.11/logging/__init__.py", line 1634, in _log
      self.handle(record)
    File "/usr/lib/python3.11/logging/__init__.py", line 1644, in handle
      self.callHandlers(record)
    File "/usr/lib/python3.11/logging/__init__.py", line 1706, in callHandlers
      hdlr.handle(record)
    File "/usr/lib/python3.11/logging/__init__.py", line 974, in handle
      rv = self.filter(record)
           ^^^^^^^^^^^^^^^^^^^
    File "/usr/lib/python3.11/logging/__init__.py", line 830, in filter
      result = f.filter(record)
               ^^^^^^^^^^^^^^^^
    File "/usr/lib/python3/dist-packages/sphinx/util/logging.py", line 426, in filter
      raise exc
  sphinx.errors.SphinxWarning: /home/alex/lsrc/qemu.git/qemu-options.hx:3884:'any' reference target not found: hub

  Warning, treated as error:
  /home/alex/lsrc/qemu.git/qemu-options.hx:3884:'any' reference target not found: hub

So it appears deep in sphinx itself and not any of our config bits... I
can't work out why its looking up hub as a reference though.

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro