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@xxxxxxxxxx> > --- > 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@xxxxxxxxxx>
Attachment:
signature.asc
Description: PGP signature
-- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
