diff options
Diffstat (limited to 'docs/misc')
-rw-r--r-- | docs/misc/console.txt | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/docs/misc/console.txt b/docs/misc/console.txt new file mode 100644 index 0000000000..73ca8355f4 --- /dev/null +++ b/docs/misc/console.txt @@ -0,0 +1,91 @@ +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. + +When using stubdoms the serial cards are still emulated by qemu (this +time running in the stubdom), the number of serial cards and where the +output goes is still specified using qemu command line options. +The difference is that for each emulated serial card there must be a pv +console connection between the stubdom and dom0 to export the serial +output from the stubdom to dom0. The pv console backend for stubdom's pv +consoles is always ioemu because multiple pv consoles support is a +requirement in this case, considering that minios has its own pv console +too. In order to simplify the setup when using stubdoms the hvm guest +can only have one pv console with xenstored as backend (the stubdom +could provide pv console backends to the hvm guest but then it would +need another pv console connection for each console backend to export +the pty to dom0). |