10:21 a.m.
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(a)redhat.com>
---
docs/formatdomain.html.in | 212 +++++++++++++++++++++++++++++++++-------------
1 file changed, 152 insertions(+), 60 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 7c819d8bf..4630743c8 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -6514,6 +6514,7 @@ qemu-kvm -net nic,model=? /dev/null
<pre>
...
<devices>
+ <!-- Serial port -->
<serial type='pty'>
<source path='/dev/pts/3'/>
<target port='0'/>
@@ -6521,98 +6522,189 @@ qemu-kvm -net nic,model=? /dev/null
</devices>
...</pre>
+<pre>
+...
+<devices>
+ <!-- USB serial port -->
+ <serial type='pty'>
+ <target type='usb' 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 can be used to pick between <code>isa-serial</code>,
- <code>usb-serial</code>, <code>pci-serial</code> and,
- <span class="since">since 3.10.0</span>,
<code>spapr-vty</code>,
+ The <code>target</code> target element can have an optional
+ <code>port</code> attribute, which specifies the port number (starting
+ from 0), and an optional <code>type</code> attribute which can be used
+ to pick the guest-visible device: values available ever
+ <span class="since">since 1.0.2</span> are
<code>isa-serial</code>,
+ <code>usb-serial</code> and <code>pci-serial</code>;
+ <span class="since">since 3.10.0</span>
<code>spapr-vty</code>,
<code>pl011</code>, <code>sclpconsole</code> and
- <code>sclplmconsole</code>.
- Some values are not compatible with all architecture and machine types;
- if the value is missing altogether, libvirt will try to pick an
- appropriate 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.
+ <code>sclplmconsole</code> can be used as well. Some values are not
+ compatible with all architecture and machine types, and if the value is
+ missing altogether, libvirt will try to pick an appropriate default.
+ Some of the types support configuring the guest-visible device
+ address as <a href="#elementsAddress">documented above</a>.
+ </p>
+
+ <p>
+ For the relationship between serial ports and consoles,
+ <a href="#elementCharSerialAndConsole">see below</a>.
</p>
<h6><a id="elementCharConsole">Console</a></h6>
+<pre>
+...
+<devices>
+ <!-- Serial console -->
+ <console type='pty'>
+ <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'/>
+ <target type='virtio' port='0'/>
+ </console>
+</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>,
+ <code>virtio</code>, <code>xen</code>,
<code>lxc</code>,
+ <code>uml</code> and <code>openvz</code>. The
<code>sclp</code> and
+ <code>sclplm</code> values are supported for compatibility reasons but
+ should not be used for new guests: use the <code>sclpconsole</code>
+ and <code>sclplmconsole</code> values, respectively, with the
+ <code>serial</code> element instead.
+ </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">h...;.
+ <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>
- 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:
+ Both emulated and paravirtualized serial consoles have advantages and
+ disadvantages:
</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>
+ 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 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>
+ 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 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">h...>)
- <span class="since">Since 0.8.3</span>
+ A configuration such as:
</p>
<pre>
...
-<devices>
+</devices>
<console type='pty'>
- <source path='/dev/pts/4'/>
- <target port='0'/>
+ <target type='serial'/>
</console>
-
- <!-- KVM virtio console -->
<console type='pty'>
- <source path='/dev/pts/5'/>
- <target type='virtio' port='0'/>
+ <target type='virtio'/>
</console>
</devices>
...</pre>
+ <p>
+ 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>
- <!-- KVM S390 sclp console -->
- <console type='pty'>
- <source path='/dev/pts/1'/>
- <target type='sclp' port='0'/>
- </console>
+</devices>
+ <serial type='pty'/>
+</devices>
+...</pre>
+
+<pre>
+...
+</devices>
+ <console type='pty'/>
+</devices>
+...</pre>
+
+<pre>
+...
+</devices>
+ <serial type='pty'/>
+ <console type='pty'/>
</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 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.13.6