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

[Alex Bennée]

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


>  ``-chardev 
> vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]``
>      Connect to a QEMU text console. ``vc`` may optionally be given a
>      specific size.

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro