| Message ID | 1455638581-5912-1-git-send-email-peter.maydell@linaro.org |
|---|---|
| State | New |
| Headers | show |
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
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?
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
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>
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
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
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
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}
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(-)