[libvirt] [PATCH v2 22/21] docs: Improve documentation for serial consoles
Pavel Hrdina
phrdina at redhat.com
Thu Nov 23 17:05:57 UTC 2017
On Wed, Nov 22, 2017 at 04:24:07PM +0100, Andrea Bolognani wrote:
> 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 at 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.
This part will need some tuning since we cannot rename isa-serial to
isa.
> </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,
s/architecture/architectures/
> + 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.
I would probably rephrase that to something like this:
Some of the values listed above are not compatible with all
architectures and machine types. If neither the target type nor
the target model is specified, libvirt will choose default values,
which are in general the best choice.
The original wording kind of feels strictly limiting and like you
shouldn't try to configure it at all.
> + </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">http://fedoraproject.org/wiki/Features/VirtioSerial</a>)
> - <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">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'>
> + <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>
Nice job, this new documentation helps a lot with all the mess that we
have for serial and console devices.
Looks more than good to me :) but as I've mentioned in previous patch,
the rewrite should be done as a separate patch without the new elements.
Pavel
> +
> +<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
>
> --
> libvir-list mailing list
> libvir-list at redhat.com
> https://www.redhat.com/mailman/listinfo/libvir-list
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20171123/2cbb6b53/attachment-0001.sig>
More information about the libvir-list
mailing list