9:22 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 | 230 ++++++++++++++++++++++++++++++++++------------
1 file changed, 172 insertions(+), 58 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index fd85b7633..2abbadd53 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -6518,80 +6518,81 @@ 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' port='0'>
+ <model name='usb-serial'/>
+ </target>
+ <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</code>,
<code>usb</code>,
- <code>pci</code> and, <span class="since">since
3.10.0</span>,
- <code>spapr-vio</code>, <code>system</code> and
<code>sclp</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</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</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 which indicates what bus the
+ serial device is connected to:
+ <span class="since">since 3.10.0</span>, valid values are
+ <code>isa</code>, <code>usb</code>,
<code>pci</code>,
+ <code>spapr-vio</code>, <code>system</code> and
<code>sclp</code>; for
+ backwards compatibility, <code>isa-serial</code>,
+ <code>usb-serial</code> and <code>pci-serial</code>
(available
+ <span class="since">since 1.0.2</span>) are accepted as
well.
</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:
+ <span class="since">Since 3.10.0</span>, the
<code>target</code>
+ element can have an optional <code>model</code> subelement, whose
+ <code>name</code> attribute can be used to choose the concrete,
+ hypervisor-specific device name: valid values are
+ <code>isa-serial</code>, <code>usb-serial</code>,
+ <code>pci-serial</code>, <code>spapr-vty</code>,
<code>pl011</code>,
+ <code>sclpconsole</code> and <code>sclplmconsole</code>.
</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>
+ Some of the values listed above are not compatible with all
+ architecture and machine types, and if the value is missing altogether,
+ libvirt will try to pick an appropriate default. In general, it's a
+ good idea to specify neither the target type nor the target model,
+ leave the task of choosing values up to libvirt, and don't change the
+ values afterward.
+ </p>
<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>
+ Some of the types support configuring the guest-visible device
+ address as <a href="#elementsAddress">documented above</a>.
+ 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/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'/>
@@ -6600,21 +6601,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>,
+ <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> target models, 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>
+ 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'>
+ <target type='serial'/>
+ </console>
<console type='pty'>
- <source path='/dev/pts/1'/>
- <target type='sclp' port='0'/>
+ <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.14.3