Re: [libvirt] [PATCH v3 01/28] 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 | 210 +++++++++++++++++++++++++++++++++------------- 1 file changed, 154 insertions(+), 56 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 505676354..12d7fb407 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -6518,77 +6518,62 @@ 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 + on x86 machine types), + <code>usb-serial</code> (usable whenever USB support is available) + and <code>pci-serial</code> (usable whenever PCI support is available). </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: + If any of the attributes is not specified by the user, libvirt will + choose a value suitable for most users. </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">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>.