Re: [libvirt] [PATCH v2 22/21] 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(a)redhat.com&gt; --- 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> ... &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' port='0'&gt; + &lt;model name='usb-serial'/&gt; + &lt;/target&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 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>&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</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 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>&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> + 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> ... &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; @@ -6600,21 +6601,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>, + <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> ... -&lt;devices&gt; - &lt;!-- KVM S390 sclp console --&gt; +&lt;/devices&gt; + &lt;console type='pty'&gt; + &lt;target type='serial'/&gt; + &lt;/console&gt; &lt;console type='pty'&gt; - &lt;source path='/dev/pts/1'/&gt; - &lt;target type='sclp' port='0'/&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> -- 2.14.3 -- libvir-list mailing list libvir-list(a)redhat.com https://www.redhat.com/mailman/listinfo/libvir-list