[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[libvirt] [PATCH 15/14] 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>
---
 docs/formatdomain.html.in | 212 +++++++++++++++++++++++++++++++++-------------
 1 file changed, 152 insertions(+), 60 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 7c819d8bf..4630743c8 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -6514,6 +6514,7 @@ 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;
@@ -6521,98 +6522,189 @@ qemu-kvm -net nic,model=? /dev/null
 &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;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-serial</code>,
-      <code>usb-serial</code>, <code>pci-serial</code> and,
-      <span class="since">since 3.10.0</span>, <code>spapr-vty</code>,
+      The <code>target</code> target 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 can be used
+      to pick the guest-visible device: values available ever
+      <span class="since">since 1.0.2</span> are <code>isa-serial</code>,
+      <code>usb-serial</code> and <code>pci-serial</code>;
+      <span class="since">since 3.10.0</span> <code>spapr-vty</code>,
       <code>pl011</code>, <code>sclpconsole</code> and
-      <code>sclplmconsole</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-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.
+      <code>sclplmconsole</code> can be used as well. Some values are not
+      compatible with all architecture and machine types, and if the value is
+      missing altogether, libvirt will try to pick an appropriate default.
+      Some of the types support configuring the guest-visible device
+      address as <a href="#elementsAddress">documented above</a>.
+    </p>
+
+    <p>
+      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/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;
+    &lt;target type='virtio' port='0'/&gt;
+  &lt;/console&gt;
+&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> values, 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";>http://fedoraproject.org/wiki/Features/VirtioSerial</a>.
+      <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>
-      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:
+      Both emulated and paravirtualized serial consoles have advantages and
+      disadvantages:
     </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>
+        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 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>
+        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 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>
+      A configuration such as:
     </p>
 
 <pre>
 ...
-&lt;devices&gt;
+&lt;/devices&gt;
   &lt;console type='pty'&gt;
-    &lt;source path='/dev/pts/4'/&gt;
-    &lt;target port='0'/&gt;
+    &lt;target type='serial'/&gt;
   &lt;/console&gt;
-
-  &lt;!-- KVM virtio console --&gt;
   &lt;console type='pty'&gt;
-    &lt;source path='/dev/pts/5'/&gt;
-    &lt;target type='virtio' port='0'/&gt;
+    &lt;target type='virtio'/&gt;
   &lt;/console&gt;
 &lt;/devices&gt;
 ...</pre>
 
+    <p>
+      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;!-- KVM S390 sclp console --&gt;
-  &lt;console type='pty'&gt;
-    &lt;source path='/dev/pts/1'/&gt;
-    &lt;target type='sclp' port='0'/&gt;
-  &lt;/console&gt;
+&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>
-      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 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.13.6


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]