[libvirt] [PATCH v3 01/28] docs: Improve documentation for serial consoles

[Pavel Hrdina]

On Sun, Nov 26, 2017 at 11:25:22PM +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 | 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>
>  ...
>  <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-serial' port='0'/>
> +    <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 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><address/></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><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: 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><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>
> -      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>.

I prefer the original wording where we have explicit list of types that
support the <address/> element.  Having a link to the generic address
description is definitely better but having a list of serial types
that support address can help users a lot.  From the following patches
only "system-serial" and "sclp-serial" cannot have an address element.

Currently this sentence should be: "All of the types support...".
Later patches should modify this statement to exclude the types that
don't support specifying address.

Reviewed-by: Pavel Hrdina <phrdina at redhat.com>
-------------- 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/20171127/40172083/attachment-0001.sig>