External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-03-20 07:59:00 +00:00
Code

docs: Improve documentation for serial consoles

Browse Source 
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>
This commit is contained in:
Andrea Bolognani 2017-11-15 17:15:15 +01:00
parent c32fda72e3
commit 4567cecb37
1 changed files with 164 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

224
docs/formatdomain.html.in
View File

@ -6518,77 +6518,68 @@ qemu-kvm -net nic,model=? /dev/null
<pre>
...
&lt;devices&gt;
&lt;!-- Serial port --&gt;
&lt;serial type='pty'&gt;
&lt;source path='/dev/pts/3'/&gt;
&lt;target port='0'/&gt;
&lt;/serial&gt;
&lt;/devices&gt;
...</pre>
<pre>
...
&lt;devices&gt;
&lt;!-- USB serial port --&gt;
&lt;serial type='pty'&gt;
&lt;target type='usb-serial' port='0'/&gt;
&lt;address type='usb' bus='0' port='1'/&gt;
&lt;/serial&gt;
&lt;/devices&gt;
...</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>&lt;address/&gt;</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>&lt;address/&gt;</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>&lt;serial&gt;</code> element exists, the console
element will be copied to the serial element. If a <code>&lt;serial&gt;</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>
...
&lt;devices&gt;
&lt;!-- Serial console --&gt;
&lt;console type='pty'&gt;
&lt;source path='/dev/pts/4'/&gt;
&lt;target port='0'/&gt;
&lt;source path='/dev/pts/2'/&gt;
&lt;target type='serial' port='0'/&gt;
&lt;/console&gt;
&lt;/devices&gt;
...</pre>
<pre>
...
&lt;!-- KVM virtio console --&gt;
&lt;console type='pty'&gt;
&lt;source path='/dev/pts/5'/&gt;
@ -6597,21 +6588,134 @@ qemu-kvm -net nic,model=? /dev/null
&lt;/devices&gt;
...</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>
...
&lt;devices&gt;
&lt;!-- KVM S390 sclp console --&gt;
&lt;/devices&gt;
&lt;console type='pty'&gt;
&lt;source path='/dev/pts/1'/&gt;
&lt;target type='sclp' port='0'/&gt;
&lt;target type='serial'/&gt;
&lt;/console&gt;
&lt;console type='pty'&gt;
&lt;target type='virtio'/&gt;
&lt;/console&gt;
&lt;/devices&gt;
...</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>
...
&lt;/devices&gt;
&lt;serial type='pty'/&gt;
&lt;/devices&gt;
...</pre>
<pre>
...
&lt;/devices&gt;
&lt;console type='pty'/&gt;
&lt;/devices&gt;
...</pre>
<pre>
...
&lt;/devices&gt;
&lt;serial type='pty'/&gt;
&lt;console type='pty'/&gt;
&lt;/devices&gt;
...</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>