Xen devel - Aug 2010 - [PATCH] document how multiple consoles work

Hi all,
this patch adds a console.txt document that explains how multiple
consoles and multiple backends work after the recent patches to
libxl, qemu, xenconsoled and xenconsole.


Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com>

---

diff -r f45026ec8db5 docs/misc/console.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/misc/console.txt	Thu Aug 12 12:00:37 2010 +0100
@@ -0,0 +1,78 @@
+Xen PV Console notes
+------------------------------------------------------------------------
+                                                      Stefano Stabellini
+                                        stefano.stabellini@eu.citrix.com
+
+
+Xen traditionally provided a single pv console to pv guests, storing the
+relevant information in xenstore under /local/domain/$DOMID/console.
+
+Now many years after the introduction of the pv console we have
+multiple pv consoles support for pv and hvm guests; multiple pv
+console backends (qemu and xenconsoled) and emulated serial cards too.
+
+This document tries to describe how the whole system works and how the
+different components interact with each others.
+
+The first PV console path in xenstore remains:
+
+/local/domain/$DOMID/console
+
+the other PV consoles follow the conventional xenstore device path and
+live in:
+
+/local/domain/$DOMID/device/console/$DEVID.
+
+The output of a PV console, whether it should be a file, a pty, a
+socket, or something else, is specified by the toolstack in the xenstore
+node "output", under the relevant console section.
+For example:
+
+# xenstore-read /local/domain/26/device/console/1/output
+pty
+
+The backend chosen for a particular console is specified by the
+toolstack in the "type" node on xenstore, under the relevant console
+section.
+For example:
+
+# xenstore-read /local/domain/26/console/type
+xenconsoled
+
+The supported values are only xenconsoled or ioemu; xenconsoled has
+several limitations: it can only be used for the first PV console and it
+can only have a pty as output.
+
+If the output is a pty, backends write the device name to the "tty"
node
+in xenstore under the relevant console path.
+
+Emulated serials are provided by qemu-dm only to hvm guests; the number
+of emulated serials depends on how many "-serial" command line
options
+are given to qemu. The output of a serial is specified as argument to
+the -serial command line option to qemu. Qemu writes the tty name to
+xenstore in the following path:
+
+/local/domain/$DOMID/serial/$SERIAL_NUM/tty
+
+
+xenconsole is the tool to connect to a PV console or an emulated serial
+that has a pty as output. Xenconsole takes a domid as parameter plus an
+optional console type (pv for PV consoles or serial for emulated
+serials) and console number. Depending on the type and console
+number, xenconsole will look for the tty node in different xenstore
+paths, as described above.  If the user doesn''t specify the console
type
+xenconsole will try to guess: if the guest is a pv guest it defaults to
+PV console, if the guest is an hvm guest it defaults to emulated serial.
+
+By default xl creates a pv console for hvm guests, plus an emulated
+serial if the user specified ''serial = "pty"'' in
the VM config file.
+Considering that xenconsole defaults to emulated serials for hvm guests,
+executing xl create -c "domain" causes xenconsole to attach to the
+emulated serial tty. This is most probably what the user wanted because
+currently no bootloaders support xen pv consoles so the only way to
+interact with a bootloader like grub over a console is to use the
+emulated serial.
+However the pv console is still easy to use with Linux PV on HVM guests:
+the user just need to pass "console=hvc0" to the kernel command line
and
+then execute "xl console -t pv <domain>" to connect to it.
+

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Stefano Stabellini writes ("[Xen-devel] [PATCH] document how multiple
consoles work"):
> this patch adds a console.txt document that explains how multiple
> consoles and multiple backends work after the recent patches to
> libxl, qemu, xenconsoled and xenconsole.
> 
> 
> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

Ian.

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel