[Qemu-trivial] [PATCH] qemu-options.hx: Improve documentation of chardev multiplexing mode

[Qemu-trivial] [PATCH] qemu-options.hx: Improve documentation of chardev multiplexing mode

[Peter Maydell]

The current documentation of chardev mux=on is rather brief and opaque;
expand it to hopefully be a bit more helpful.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
There was some discussion on #qemu yesterday evening about multiplexing,
and "make the docs a bit less confusing" was one suggestion...
---
 qemu-options.hx | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 2f0465e..6b46dd4 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2162,8 +2162,26 @@ All devices must have an id, which can be any string up to 127 characters long.
 It is used to uniquely identify this device in other command line directives.
 
 A character device may be used in multiplexing mode by multiple front-ends.
+Specify @option{mux=on} to enable this mode.
+A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
+backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
+If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
+create a multiplexer with your specified ID, and you can then configure multiple
+front ends to use that chardev ID for their input/output. Up to four different
+front ends can be connected to a single multiplexed chardev. (Without
+multiplexing enabled, a chardev can only be used by a single front end.)
+For instance you could use this to allow a single stdio chardev to be used by
+two serial ports and the QEMU monitor.
+
 The key sequence of @key{Control-a} and @key{c} will rotate the input focus
-between attached front-ends. Specify @option{mux=on} to enable this mode.
+of a multiplexed character device between attached front-ends.
+
+You can have more than one multiplexer in a system configuration; for instance
+you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
+multiplexed between the QEMU monitor and a parallel port.
+
+There is currently no support for multiplexing in the other direction
+(where a single QEMU front end takes input and output from multiple chardevs).
 
 Every backend supports the @option{logfile} option, which supplies the path
 to a file to record all data transmitted via the backend. The @option{logappend}
-- 
1.9.1

Re: [Qemu-trivial] [PATCH] qemu-options.hx: Improve documentation of chardev multiplexing mode

[Paolo Bonzini]

On 16/02/2016 17:03, Peter Maydell wrote:
> The current documentation of chardev mux=on is rather brief and opaque;
> expand it to hopefully be a bit more helpful.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> There was some discussion on #qemu yesterday evening about multiplexing,
> and "make the docs a bit less confusing" was one suggestion...
> ---
>  qemu-options.hx | 20 +++++++++++++++++++-
>  1 file changed, 19 insertions(+), 1 deletion(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 2f0465e..6b46dd4 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2162,8 +2162,26 @@ All devices must have an id, which can be any string up to 127 characters long.
>  It is used to uniquely identify this device in other command line directives.
>  
>  A character device may be used in multiplexing mode by multiple front-ends.
> +Specify @option{mux=on} to enable this mode.
> +A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
> +backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
> +If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
> +create a multiplexer with your specified ID, and you can then configure multiple
> +front ends to use that chardev ID for their input/output. Up to four different
> +front ends can be connected to a single multiplexed chardev. (Without
> +multiplexing enabled, a chardev can only be used by a single front end.)
> +For instance you could use this to allow a single stdio chardev to be used by
> +two serial ports and the QEMU monitor.
> +
>  The key sequence of @key{Control-a} and @key{c} will rotate the input focus
> -between attached front-ends. Specify @option{mux=on} to enable this mode.
> +of a multiplexed character device between attached front-ends.
> +
> +You can have more than one multiplexer in a system configuration; for instance
> +you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
> +multiplexed between the QEMU monitor and a parallel port.
> +
> +There is currently no support for multiplexing in the other direction
> +(where a single QEMU front end takes input and output from multiple chardevs).
>  
>  Every backend supports the @option{logfile} option, which supplies the path
>  to a file to record all data transmitted via the backend. The @option{logappend}
> 

Very nice, thanks!  I'm queuing this patch.

Paolo

Re: [Qemu-trivial] [Qemu-devel] [PATCH] qemu-options.hx: Improve documentation of chardev multiplexing mode

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1026 bytes --]

On 02/16/2016 09:03 AM, Peter Maydell wrote:
> The current documentation of chardev mux=on is rather brief and opaque;
> expand it to hopefully be a bit more helpful.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> There was some discussion on #qemu yesterday evening about multiplexing,
> and "make the docs a bit less confusing" was one suggestion...
> ---
>  qemu-options.hx | 20 +++++++++++++++++++-
>  1 file changed, 19 insertions(+), 1 deletion(-)
> 

Looks like a strict improvement, so:
Reviewed-by: Eric Blake <eblake@redhat.com>

That said, how does one enter a literal <ctrl-a> to the front end,
instead of getting it interpreted by the mux backend as a signal of
whether to rotate to the next front end?  Is <ctrl-a> an escaping
character, such that sending it twice results in a single instance being
sent to the current guest front end hooked up to the mux?

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

Re: [Qemu-trivial] [Qemu-devel] [PATCH] qemu-options.hx: Improve documentation of chardev multiplexing mode

[Laszlo Ersek]

On 02/16/16 17:03, Peter Maydell wrote:
> The current documentation of chardev mux=on is rather brief and opaque;
> expand it to hopefully be a bit more helpful.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> There was some discussion on #qemu yesterday evening about multiplexing,
> and "make the docs a bit less confusing" was one suggestion...
> ---
>  qemu-options.hx | 20 +++++++++++++++++++-
>  1 file changed, 19 insertions(+), 1 deletion(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 2f0465e..6b46dd4 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2162,8 +2162,26 @@ All devices must have an id, which can be any string up to 127 characters long.
>  It is used to uniquely identify this device in other command line directives.
>  
>  A character device may be used in multiplexing mode by multiple front-ends.
> +Specify @option{mux=on} to enable this mode.
> +A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
> +backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
> +If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
> +create a multiplexer with your specified ID, and you can then configure multiple
> +front ends to use that chardev ID for their input/output. Up to four different
> +front ends can be connected to a single multiplexed chardev. (Without
> +multiplexing enabled, a chardev can only be used by a single front end.)
> +For instance you could use this to allow a single stdio chardev to be used by
> +two serial ports and the QEMU monitor.
> +
>  The key sequence of @key{Control-a} and @key{c} will rotate the input focus
> -between attached front-ends. Specify @option{mux=on} to enable this mode.
> +of a multiplexed character device between attached front-ends.
> +
> +You can have more than one multiplexer in a system configuration; for instance
> +you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
> +multiplexed between the QEMU monitor and a parallel port.
> +
> +There is currently no support for multiplexing in the other direction
> +(where a single QEMU front end takes input and output from multiple chardevs).
>  
>  Every backend supports the @option{logfile} option, which supplies the path
>  to a file to record all data transmitted via the backend. The @option{logappend}
> 

I'm a big fan of muxing the stdio backend between the (human) monitor
and the guest's serial console:

  -chardev stdio,signal=off,mux=on,id=char0 \
  -mon chardev=char0,mode=readline,default \
  -serial chardev:char0 \

I think if you could mention the following in the above, that would be
even more helpful:
- how to enter a real Control-A character (relevant when typing at the
  guest's shell prompt, over serial)
- not strictly related, but a warning about using this in "screen"
  (I use "screen" all the time to capture serial IO) -- Control-A is
  also piggy-backed by "screen"
- how the initially active frontend gets selected
- the fact that frontends use different syntaxes to refer to the
  backend. You have two examples in the text being added ("for
  instance, ..."), so I think it would be really helpful to provide
  actual command line options for those.

Just my two cents. The patch looks great.

Thanks
Laszlo

Re: [Qemu-trivial] [PATCH] qemu-options.hx: Improve documentation of chardev multiplexing mode

[Kashyap Chamarthy]

On Tue, Feb 16, 2016 at 04:03:01PM +0000, Peter Maydell wrote:
> The current documentation of chardev mux=on is rather brief and opaque;
> expand it to hopefully be a bit more helpful.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
>
> ---
> There was some discussion on #qemu yesterday evening about multiplexing,
> and "make the docs a bit less confusing" was one suggestion...
> ---

Thanks for following up with the clarifying write-up.

>  qemu-options.hx | 20 +++++++++++++++++++-
>  1 file changed, 19 insertions(+), 1 deletion(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 2f0465e..6b46dd4 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2162,8 +2162,26 @@ All devices must have an id, which can be any string up to 127 characters long.
>  It is used to uniquely identify this device in other command line directives.
>  
>  A character device may be used in multiplexing mode by multiple front-ends.
> +Specify @option{mux=on} to enable this mode.
> +A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
> +backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
> +If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
> +create a multiplexer with your specified ID, and you can then configure multiple
> +front ends to use that chardev ID for their input/output. Up to four different
> +front ends can be connected to a single multiplexed chardev. (Without
> +multiplexing enabled, a chardev can only be used by a single front end.)
> +For instance you could use this to allow a single stdio chardev to be used by
> +two serial ports and the QEMU monitor.

Just noting for convenience here, looking at an old commit[1 that
notes the syntax for multiplexing 'stdio', which you mention above in
prose:

    [...]
    Muxing can be done this way:
    
        -chardev stdio,id=mux,mux=on
        -serial chardev:mux
        -monitor chardev:mux"
    [...]

[1] http://git.qemu.org/?p=qemu.git;a=commitdiff;h=c845f40

> +
>  The key sequence of @key{Control-a} and @key{c} will rotate the input focus
> -between attached front-ends. Specify @option{mux=on} to enable this mode.
> +of a multiplexed character device between attached front-ends.
> +
> +You can have more than one multiplexer in a system configuration; for instance
> +you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
> +multiplexed between the QEMU monitor and a parallel port.
> +
> +There is currently no support for multiplexing in the other direction
> +(where a single QEMU front end takes input and output from multiple chardevs).
>  
>  Every backend supports the @option{logfile} option, which supplies the path
>  to a file to record all data transmitted via the backend. The @option{logappend}

Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com>

-- 
/kashyap

Re: [Qemu-trivial] [Qemu-devel] [PATCH] qemu-options.hx: Improve documentation of chardev multiplexing mode

[Paolo Bonzini]

On 16/02/2016 17:32, Laszlo Ersek wrote:
> I'm a big fan of muxing the stdio backend between the (human) monitor
> and the guest's serial console:
> 
>   -chardev stdio,signal=off,mux=on,id=char0 \
>   -mon chardev=char0,mode=readline,default \
>   -serial chardev:char0 \

Or just "-serial mon:stdio". :)

Paolo

Re: [Qemu-trivial] [Qemu-devel] [PATCH] qemu-options.hx: Improve documentation of chardev multiplexing mode

[Laszlo Ersek]

On 02/16/16 18:02, Paolo Bonzini wrote:
> 
> 
> On 16/02/2016 17:32, Laszlo Ersek wrote:
>> I'm a big fan of muxing the stdio backend between the (human) monitor
>> and the guest's serial console:
>>
>>   -chardev stdio,signal=off,mux=on,id=char0 \
>>   -mon chardev=char0,mode=readline,default \
>>   -serial chardev:char0 \
> 
> Or just "-serial mon:stdio". :)

For what reason on earth are these three *possible* at all to tie up
into a single command line option?

... I appreciate your teaching me ancient lores, but I think I just died
a little inside.

Laszlo

Re: [Qemu-trivial] [Qemu-devel] [PATCH] qemu-options.hx: Improve documentation of chardev multiplexing mode

[Peter Maydell]

On 16 February 2016 at 17:57, Laszlo Ersek <lersek@redhat.com> wrote:
> On 02/16/16 18:02, Paolo Bonzini wrote:
>>
>>
>> On 16/02/2016 17:32, Laszlo Ersek wrote:
>>> I'm a big fan of muxing the stdio backend between the (human) monitor
>>> and the guest's serial console:
>>>
>>>   -chardev stdio,signal=off,mux=on,id=char0 \
>>>   -mon chardev=char0,mode=readline,default \
>>>   -serial chardev:char0 \
>>
>> Or just "-serial mon:stdio". :)
>
> For what reason on earth are these three *possible* at all to tie up
> into a single command line option?

Legacy convenience options. The muxing of the monitor and the
console way predates the implementation of chardev backends
and a generic mux.

QEMU's command line options are full of this kind of thing, where
we started off with a special purpose thingy that got a nice
short comprehensible option to turn it on and off, and then later
we got a general purpose facility with lots of orthogonal bells
and whistles. If you're lucky then the special-purpose legacy
option is exactly equivalent to some longer general purpose
option set; sometimes it isn't...

thanks
-- PMM