Roman Penyaev <[email protected]> writes:
> On Tue, Jan 21, 2025 at 4:02 PM Alex Bennée <[email protected]> wrote:
>>
>> Roman Penyaev <[email protected]> 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 <[email protected]>
>> > Cc: "Marc-André Lureau" <[email protected]>
>> > Cc: [email protected]
>> > ---
>> > 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
