From 07ed5aa86d223b1e99ef716429be60c1823ce0f5 Mon Sep 17 00:00:00 2001 Message-Id: <07ed5aa86d223b1e99ef716429be60c1823ce0f5@dist-git> From: Andrea Bolognani Date: Wed, 29 Nov 2017 16:22:55 +0100 Subject: [PATCH] docs: Improve documentation for serial consoles Our current documentation is missing some information and doesn't do a great job at explaining how the and elements are connected. Let's try to fix that. Signed-off-by: Andrea Bolognani Reviewed-by: Pavel Hrdina (cherry picked from commit 4567cecb372c48095fce23ce3040d1c687cc3640) https://bugzilla.redhat.com/show_bug.cgi?id=1449265 https://bugzilla.redhat.com/show_bug.cgi?id=1511421 https://bugzilla.redhat.com/show_bug.cgi?id=1512929 https://bugzilla.redhat.com/show_bug.cgi?id=1512934 Signed-off-by: Jiri Denemark --- docs/formatdomain.html.in | 224 +++++++++++++++++++++++++++++++++------------- 1 file changed, 164 insertions(+), 60 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 4f28dce355..f57a124056 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -6434,77 +6434,68 @@ qemu-kvm -net nic,model=? /dev/null 
 ...
 <devices>
+  <!-- Serial port -->
   <serial type='pty'>
     <source path='/dev/pts/3'/>
     <target port='0'/>
   </serial>
 </devices>
+...
+ +
+...
+<devices>
+  <!-- USB serial port -->
+  <serial type='pty'>
+    <target type='usb-serial' port='0'/>
+    <address type='usb' bus='0' port='1'/>
+  </serial>
+</devices>
 ...

- target can have a port attribute, which - specifies the port number. Ports are numbered starting from 0. There are - usually 0, 1 or 2 serial ports. There is also an optional - type attribute since 1.0.2 - which has three choices for its value, one is isa-serial, - then usb-serial and last one is pci-serial. - If type is missing, isa-serial will be used by - default. For usb-serial an optional sub-element - <address/> with type='usb' can tie the - device to a particular controller, documented above. - Similarly, pci-serial can be used to attach the device to - the pci bus (since 1.2.16). Again, it has - optional sub-element <address/> with - type='pci' to select desired location on the PCI bus. + The target element can have an optional port + attribute, which specifies the port number (starting from 0), and an + optional type attribute: valid values are, + since 1.0.2, isa-serial (usable + with x86 guests), usb-serial (usable whenever USB support + is available) and pci-serial (usable whenever PCI support + is available). +

+ +

+ If any of the attributes is not specified by the user, libvirt will + choose a value suitable for most users. +

+ +

+ All of the target types support configuring the guest-visible device + address as documented above; more + specifically, acceptable address types are isa (for + isa-serial), usb (for usb-serial) + and pci (for pci-serial). +

+ +

+ For the relationship between serial ports and consoles, + see below.

Console
-

- The console element is used to represent interactive consoles. Depending - on the type of guest in use, the consoles might be paravirtualized devices, - or they might be a clone of a serial device, according to the following - rules: -

- -
    -
  • If no targetType attribute is set, then the default - device type is according to the hypervisor's rules. The default - type will be added when re-querying the XML fed into libvirt. - For fully virtualized guests, the default device type will usually - be a serial port.
    • -
  • If the targetType attribute is serial, - then if no <serial> element exists, the console - element will be copied to the serial element. If a <serial> - element does already exist, the console element will be ignored.
    • -
  • If the targetType attribute is not serial, - it will be treated normally.
    • -
  • Only the first console element may use a targetType - of serial. Secondary consoles must all be paravirtualized. -
    • -
  • On S390, the console element may use a - targetType of sclp or sclplm - (line mode). SCLP is the native console type for S390. There's no - controller associated to SCLP consoles. - Since 1.0.2 -
    • -
- -

- A virtio console device is exposed in the - guest as /dev/hvc[0-7] (for more information, see - http://fedoraproject.org/wiki/Features/VirtioSerial) - Since 0.8.3 -

- 
 ...
 <devices>
+  <!-- Serial console -->
   <console type='pty'>
-    <source path='/dev/pts/4'/>
-    <target port='0'/>
+    <source path='/dev/pts/2'/>
+    <target type='serial' port='0'/>
   </console>
+</devices>
+...
+
+...
   <!-- KVM virtio console -->
   <console type='pty'>
     <source path='/dev/pts/5'/>
@@ -6513,21 +6504,134 @@ qemu-kvm -net nic,model=? /dev/null
 </devices>
 ...
+

+ The console element is used to represent interactive + serial consoles. Depending on the type of guest in use and the specifics + of the configuration, the console element might represent + the same device as an existing serial element or a separate + device. +

+ +

+ A target subelement is supported and works the same + way as with the serial element + (see above for details). + Valid values for the type attribute are: + serial (described below); + virtio (usable whenever VirtIO support is available); + xen, lxc, uml and + openvz (available when the corresponding hypervisor is in + use); sclp and sclplm (usable for s390 and + s390x QEMU guests). +

+ +

+ Of the target types listed above, serial is special in + that it doesn't represents a separate device, but rather the same + device as the first serial element. Due to this, there can + only be a single console element with target type + serial per guest. +

+ +

+ Virtio consoles are usually accessible as /dev/hvc[0-7] + from inside the guest; for more information, see + http://fedoraproject.org/wiki/Features/VirtioSerial. + Since 0.8.3 +

+ +

+ For the relationship between serial ports and consoles, + see below. +

+ +
Relationship between serial ports and consoles
+ +

+ Due to hystorical reasons, the serial and + console elements have partially overlapping scopes. +

+ +

+ In general, both elements are used to configure one or more serial + consoles to be used for interacting with the guest. The main difference + between the two is that serial is used for emulated, + usually native, serial consoles, whereas console is used + for paravirtualized ones. +

+ +

+ Both emulated and paravirtualized serial consoles have advantages and + disadvantages: +

+ +
    +
  • + emulated serial consoles are usually initialized much earlier than + paravirtualized ones, so they can be used to control the bootloader + and display both firmware and early boot messages; +
    • +
  • + on several platforms, there can only be a single emulated serial + console per guest but paravirtualized consoles don't suffer from the + same limitation. +
    • +
+ +

+ A configuration such as: +

+ 
 ...
-<devices>
-  <!-- KVM S390 sclp console -->
+</devices>
   <console type='pty'>
-    <source path='/dev/pts/1'/>
-    <target type='sclp' port='0'/>
+    <target type='serial'/>
+  </console>
+  <console type='pty'>
+    <target type='virtio'/>
   </console>
 </devices>
 ...

- If the console is presented as a serial port, the target - element has the same attributes as for a serial port. There is usually - only 1 console. + will work on any platform and will result in one emulated serial console + for early boot logging / interactive / recovery use, and one + paravirtualized serial console to be used eg. as a side channel. Most + people will be fine with having just the first console + element in their configuration. +

+ +

+ Note that, due to the compatibility concerns mentioned earlier, all the + following configurations: +

+ +
+...
+</devices>
+  <serial type='pty'/>
+</devices>
+...
+ +
+...
+</devices>
+  <console type='pty'/>
+</devices>
+...
+ +
+...
+</devices>
+  <serial type='pty'/>
+  <console type='pty'/>
+</devices>
+...
+ +

+ will be treated the same and will result in a single emulated serial + console being available to the guest.

Channel
-- 2.15.1