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@xxxxxxxxxxxxx>
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
+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:
+the other PV consoles follow the conventional xenstore device path and
+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.
+# xenstore-read /local/domain/26/device/console/1/output
+The backend chosen for a particular console is specified by the
+toolstack in the "type" node on xenstore, under the relevant console
+# xenstore-read /local/domain/26/console/type
+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:
+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
+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