From 07ed5aa86d223b1e99ef716429be60c1823ce0f5 Mon Sep 17 00:00:00 2001

Message-Id: <07ed5aa86d223b1e99ef716429be60c1823ce0f5@dist-git>

From: Andrea Bolognani <abologna@redhat.com>

Date: Wed, 29 Nov 2017 16:22:55 +0100

Subject: [PATCH] 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@redhat.com>

Reviewed-by: Pavel Hrdina <phrdina@redhat.com>

(cherry picked from commit 4567cecb372c48095fce23ce3040d1c687cc3640)

https://bugzilla.redhat.com/show_bug.cgi?id=1449265

https://bugzilla.redhat.com/show_bug.cgi?id=1511421

https://bugzilla.redhat.com/show_bug.cgi?id=1512929

https://bugzilla.redhat.com/show_bug.cgi?id=1512934

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>

---

 docs/formatdomain.html.in | 224 +++++++++++++++++++++++++++++++++-------------

 1 file changed, 164 insertions(+), 60 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in

index 4f28dce355..f57a124056 100644

--- a/docs/formatdomain.html.in

+++ b/docs/formatdomain.html.in

@@ -6434,77 +6434,68 @@ qemu-kvm -net nic,model=? /dev/null

 ...

 <devices>

+  <!-- Serial port -->

   <serial type='pty'>

     <source path='/dev/pts/3'/>

     <target port='0'/>

   </serial>

 </devices>

+...

+

+

+...

+<devices>

+  <!-- USB serial port -->

+  <serial type='pty'>

+    <target type='usb-serial' port='0'/>

+    <address type='usb' bus='0' port='1'/>

+  </serial>

+</devices>

 ...

-      target can have a port 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

-      type attribute since 1.0.2

-      which has three choices for its value, one is isa-serial,

-      then usb-serial and last one is pci-serial.

-      If type is missing, isa-serial will be used by

-      default. For usb-serial an optional sub-element

-      <address/> with type='usb' can tie the

-      device to a particular controller, documented above.

-      Similarly, pci-serial can be used to attach the device to

-      the pci bus (since 1.2.16). Again, it has

-      optional sub-element <address/> with

-      type='pci' to select desired location on the PCI bus.

+      The target element can have an optional port

+      attribute, which specifies the port number (starting from 0), and an

+      optional type attribute: valid values are,

+      since 1.0.2, isa-serial (usable

+      with x86 guests), usb-serial (usable whenever USB support

+      is available) and pci-serial (usable whenever PCI support

+      is available).

+    

+

+    

+      If any of the attributes is not specified by the user, libvirt will

+      choose a value suitable for most users.

+    

+

+    

+      All of the target types support configuring the guest-visible device

+      address as documented above; more

+      specifically, acceptable address types are isa (for

+      isa-serial), usb (for usb-serial)

+      and pci (for pci-serial).

+    

+

+    

+      For the relationship between serial ports and consoles,

+      see below.

     
Console

-    

-      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 no targetType 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.

-      
If the targetType attribute is serial,

-        then if no <serial> element exists, the console

-        element will be copied to the serial element. If a <serial>

-        element does already exist, the console element will be ignored.

-      
If the targetType attribute is not serial,

-        it will be treated normally.

-      
Only the first console element may use a targetType

-        of serial. Secondary consoles must all be paravirtualized.

-      

-      
On S390, the console element may use a

-        targetType of sclp or sclplm

-        (line mode). SCLP is the native console type for S390. There's no

-        controller associated to SCLP consoles.

-        Since 1.0.2

-      

-    

-

-    

-      A virtio console device is exposed in the

-      guest as /dev/hvc[0-7] (for more information, see

-      http://fedoraproject.org/wiki/Features/VirtioSerial)

-      Since 0.8.3

-    

-

 ...

 <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>

+...

+

+...

   <!-- KVM virtio console -->

   <console type='pty'>

     <source path='/dev/pts/5'/>

@@ -6513,21 +6504,134 @@ qemu-kvm -net nic,model=? /dev/null

 </devices>

 ...

+    

+      The console element is used to represent interactive

+      serial consoles. Depending on the type of guest in use and the specifics

+      of the configuration, the console element might represent

+      the same device as an existing serial element or a separate

+      device.

+    

+

+    

+      A target subelement is supported and works the same

+      way as with the serial element

+      (see above for details).

+      Valid values for the type attribute are:

+      serial (described below);

+      virtio (usable whenever VirtIO support is available);

+      xen, lxc, uml and

+      openvz (available when the corresponding hypervisor is in

+      use); sclp and sclplm (usable for s390 and

+      s390x QEMU guests).

+    

+

+    

+      Of the target types listed above, serial is special in

+      that it doesn't represents a separate device, but rather the same

+      device as the first serial element. Due to this, there can

+      only be a single console element with target type

+      serial per guest.

+    

+

+    

+      Virtio consoles are usually accessible as /dev/hvc[0-7]

+      from inside the guest; for more information, see

+      http://fedoraproject.org/wiki/Features/VirtioSerial.

+      Since 0.8.3

+    

+

+    

+      For the relationship between serial ports and consoles,

+      see below.

+    

+

+    
Relationship between serial ports and consoles

+

+    

+      Due to hystorical reasons, the serial and

+      console elements have partially overlapping scopes.

+    

+

+    

+      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 serial is used for emulated,

+      usually native, serial consoles, whereas console is used

+      for paravirtualized ones.

+    

+

+    

+      Both emulated and paravirtualized serial consoles have advantages and

+      disadvantages:

+    

+

+    

+      

+        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;

+      

+      

+        on several platforms, there can only be a single emulated serial

+        console per guest but paravirtualized consoles don't suffer from the

+        same limitation.

+      

+    

+

+    

+      A configuration such as:

+    

+

 ...

-<devices>

-  <!-- KVM S390 sclp console -->

+</devices>

   <console type='pty'>

-    <source path='/dev/pts/1'/>

-    <target type='sclp' port='0'/>

+    <target type='serial'/>

+  </console>

+  <console type='pty'>

+    <target type='virtio'/>

   </console>

 </devices>

 ...

-      If the console is presented as a serial port, the target

-      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 console

+      element in their configuration.

+    

+

+    

+      Note that, due to the compatibility concerns mentioned earlier, all the

+      following configurations:

+    

+

+

+...

+</devices>

+  <serial type='pty'/>

+</devices>

+...

+

+

+...

+</devices>

+  <console type='pty'/>

+</devices>

+...

+

+

+...

+</devices>

+  <serial type='pty'/>

+  <console type='pty'/>

+</devices>

+...

+

+    

+      will be treated the same and will result in a single emulated serial

+      console being available to the guest.

     
Channel

-- 

2.15.1