From 07ed5aa86d223b1e99ef716429be60c1823ce0f5 Mon Sep 17 00:00:00 2001
Message-Id: <07ed5aa86d223b1e99ef716429be60c1823ce0f5@dist-git>
From: Andrea Bolognani <abologna@redhat.com>
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 <serial> and <console> elements
are connected. Let's try to fix that.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
(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 <jdenemar@redhat.com>
---
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
<pre>
...
<devices>
+ <!-- Serial port -->
<serial type='pty'>
<source path='/dev/pts/3'/>
<target port='0'/>
</serial>
</devices>
+...</pre>
+
+<pre>
+...
+<devices>
+ <!-- USB serial port -->
+ <serial type='pty'>
+ <target type='usb-serial' port='0'/>
+ <address type='usb' bus='0' port='1'/>
+ </serial>
+</devices>
...</pre>
<p>
- <code>target</code> can have a <code>port</code> 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
- <code>type</code> attribute <span class="since">since 1.0.2</span>
- which has three choices for its value, one is <code>isa-serial</code>,
- then <code>usb-serial</code> and last one is <code>pci-serial</code>.
- If <code>type</code> is missing, <code>isa-serial</code> will be used by
- default. For <code>usb-serial</code> an optional sub-element
- <code><address/></code> with <code>type='usb'</code> can tie the
- device to a particular controller, <a href="#elementsAddress">documented above</a>.
- Similarly, <code>pci-serial</code> can be used to attach the device to
- the pci bus (<span class="since">since 1.2.16</span>). Again, it has
- optional sub-element <code><address/></code> with
- <code>type='pci'</code> to select desired location on the PCI bus.
+ The <code>target</code> element can have an optional <code>port</code>
+ attribute, which specifies the port number (starting from 0), and an
+ optional <code>type</code> attribute: valid values are,
+ <span class="since">since 1.0.2</span>, <code>isa-serial</code> (usable
+ with x86 guests), <code>usb-serial</code> (usable whenever USB support
+ is available) and <code>pci-serial</code> (usable whenever PCI support
+ is available).
+ </p>
+
+ <p>
+ If any of the attributes is not specified by the user, libvirt will
+ choose a value suitable for most users.
+ </p>
+
+ <p>
+ All of the target types support configuring the guest-visible device
+ address as <a href="#elementsAddress">documented above</a>; more
+ specifically, acceptable address types are <code>isa</code> (for
+ <code>isa-serial</code>), <code>usb</code> (for <code>usb-serial</code>)
+ and <code>pci</code> (for <code>pci-serial</code>).
+ </p>
+
+ <p>
+ For the relationship between serial ports and consoles,
+ <a href="#elementCharSerialAndConsole">see below</a>.
</p>
<h6><a id="elementCharConsole">Console</a></h6>
- <p>
- 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:
- </p>
-
- <ul>
- <li>If no <code>targetType</code> 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.</li>
- <li>If the <code>targetType</code> attribute is <code>serial</code>,
- then if no <code><serial></code> element exists, the console
- element will be copied to the serial element. If a <code><serial></code>
- element does already exist, the console element will be ignored.</li>
- <li>If the <code>targetType</code> attribute is not <code>serial</code>,
- it will be treated normally.</li>
- <li>Only the first <code>console</code> element may use a <code>targetType</code>
- of <code>serial</code>. Secondary consoles must all be paravirtualized.
- </li>
- <li>On S390, the <code>console</code> element may use a
- <code>targetType</code> of <code>sclp</code> or <code>sclplm</code>
- (line mode). SCLP is the native console type for S390. There's no
- controller associated to SCLP consoles.
- <span class="since">Since 1.0.2</span>
- </li>
- </ul>
-
- <p>
- A virtio console device is exposed in the
- guest as /dev/hvc[0-7] (for more information, see
- <a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>)
- <span class="since">Since 0.8.3</span>
- </p>
-
<pre>
...
<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>
+...</pre>
+<pre>
+...
<!-- KVM virtio console -->
<console type='pty'>
<source path='/dev/pts/5'/>
@@ -6513,21 +6504,134 @@ qemu-kvm -net nic,model=? /dev/null
</devices>
...</pre>
+ <p>
+ The <code>console</code> element is used to represent interactive
+ serial consoles. Depending on the type of guest in use and the specifics
+ of the configuration, the <code>console</code> element might represent
+ the same device as an existing <code>serial</code> element or a separate
+ device.
+ </p>
+
+ <p>
+ A <code>target</code> subelement is supported and works the same
+ way as with the <code>serial</code> element
+ (<a href="#elementCharSerial">see above</a> for details).
+ Valid values for the <code>type</code> attribute are:
+ <code>serial</code> (described below);
+ <code>virtio</code> (usable whenever VirtIO support is available);
+ <code>xen</code>, <code>lxc</code>, <code>uml</code> and
+ <code>openvz</code> (available when the corresponding hypervisor is in
+ use); <code>sclp</code> and <code>sclplm</code> (usable for s390 and
+ s390x QEMU guests).
+ </p>
+
+ <p>
+ Of the target types listed above, <code>serial</code> is special in
+ that it doesn't represents a separate device, but rather the same
+ device as the first <code>serial</code> element. Due to this, there can
+ only be a single <code>console</code> element with target type
+ <code>serial</code> per guest.
+ </p>
+
+ <p>
+ Virtio consoles are usually accessible as <code>/dev/hvc[0-7]</code>
+ from inside the guest; for more information, see
+ <a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>.
+ <span class="since">Since 0.8.3</span>
+ </p>
+
+ <p>
+ For the relationship between serial ports and consoles,
+ <a href="#elementCharSerialAndConsole">see below</a>.
+ </p>
+
+ <h6><a id="elementCharSerialAndConsole">Relationship between serial ports and consoles</a></h6>
+
+ <p>
+ Due to hystorical reasons, the <code>serial</code> and
+ <code>console</code> elements have partially overlapping scopes.
+ </p>
+
+ <p>
+ 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 <code>serial</code> is used for emulated,
+ usually native, serial consoles, whereas <code>console</code> is used
+ for paravirtualized ones.
+ </p>
+
+ <p>
+ Both emulated and paravirtualized serial consoles have advantages and
+ disadvantages:
+ </p>
+
+ <ul>
+ <li>
+ 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;
+ </li>
+ <li>
+ on several platforms, there can only be a single emulated serial
+ console per guest but paravirtualized consoles don't suffer from the
+ same limitation.
+ </li>
+ </ul>
+
+ <p>
+ A configuration such as:
+ </p>
+
<pre>
...
-<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>
...</pre>
<p>
- If the console is presented as a serial port, the <code>target</code>
- 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 <code>console</code>
+ element in their configuration.
+ </p>
+
+ <p>
+ Note that, due to the compatibility concerns mentioned earlier, all the
+ following configurations:
+ </p>
+
+<pre>
+...
+</devices>
+ <serial type='pty'/>
+</devices>
+...</pre>
+
+<pre>
+...
+</devices>
+ <console type='pty'/>
+</devices>
+...</pre>
+
+<pre>
+...
+</devices>
+ <serial type='pty'/>
+ <console type='pty'/>
+</devices>
+...</pre>
+
+ <p>
+ will be treated the same and will result in a single emulated serial
+ console being available to the guest.
</p>
<h6><a id="elementCharChannel">Channel</a></h6>
--
2.15.1