From nobody Thu May 15 09:23:22 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1511364423807251.11306173858566; Wed, 22 Nov 2017 07:27:03 -0800 (PST) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 3109880473; Wed, 22 Nov 2017 15:27:02 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0BF815D960; Wed, 22 Nov 2017 15:27:02 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id C30241800BDE; Wed, 22 Nov 2017 15:27:01 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id vAMFOOj2022373 for ; Wed, 22 Nov 2017 10:24:24 -0500 Received: by smtp.corp.redhat.com (Postfix) id 539E462676; Wed, 22 Nov 2017 15:24:24 +0000 (UTC) Received: from inaba.usersys.redhat.com (unknown [10.40.205.30]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 1D93F62677 for ; Wed, 22 Nov 2017 15:24:18 +0000 (UTC) From: Andrea Bolognani To: libvir-list@redhat.com Date: Wed, 22 Nov 2017 16:24:07 +0100 Message-Id: <20171122152407.25200-1-abologna@redhat.com> In-Reply-To: <20171121164231.15008-1-abologna@redhat.com> References: <20171121164231.15008-1-abologna@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH v2 22/21] docs: Improve documentation for serial consoles X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.28]); Wed, 22 Nov 2017 15:27:02 +0000 (UTC) X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" Our current documentation is missing some information and doesn't do a great job at explaining how the and elements are connected. Let's try to fix that. Signed-off-by: Andrea Bolognani --- docs/formatdomain.html.in | 230 ++++++++++++++++++++++++++++++++++--------= ---- 1 file changed, 172 insertions(+), 58 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index fd85b7633..2abbadd53 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -6518,80 +6518,81 @@ qemu-kvm -net nic,model=3D? /dev/null 
 ...
 <devices>
+  <!-- Serial port -->
   <serial type=3D'pty'>
     <source path=3D'/dev/pts/3'/>
     <target port=3D'0'/>
   </serial>
 </devices>
+...
+ +
+...
+<devices>
+  <!-- USB serial port -->
+  <serial type=3D'pty'>
+    <target type=3D'usb' port=3D'0'>
+      <model name=3D'usb-serial'/>
+    </target>
+    <address type=3D'usb' bus=3D'0' port=3D'1'/>
+  </serial>
+</devices>
 ...
=20

- 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 can be used to pick between isa, usb, - pci and, since 3.10.0, - spapr-vio, system and sclp. - Some values are not compatible with all architecture and machine typ= es; - if the value is missing altogether, libvirt will try to pick an - appropriate default. - For usb an optional sub-element - <address/> with type=3D'usb' can tie= the - device to a particular controller, docu= mented above. - Similarly, pci can be used to attach the device to - the pci bus (since 1.2.16). Again, it h= as - optional sub-element <address/> with - type=3D'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 which indicates what bus the + serial device is connected to: + since 3.10.0, valid values are + isa, usb, pci, + spapr-vio, system and sclp; f= or + backwards compatibility, isa-serial, + usb-serial and pci-serial (available + since 1.0.2) are accepted as well.

=20 -
Console
-

- The console element is used to represent interactive consoles. Depen= ding - on the type of guest in use, the consoles might be paravirtualized d= evices, - or they might be a clone of a serial device, according to the follow= ing - rules: + Since 3.10.0, the target + element can have an optional model subelement, whose + name attribute can be used to choose the concrete, + hypervisor-specific device name: valid values are + isa-serial, usb-serial, + pci-serial, spapr-vty, pl011, + sclpconsole and sclplmconsole.

=20 -
    -
  • 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 <seria= l> - 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 targ= etType - of serial. Secondary consoles must all be paravirtual= ized. -
    • -
  • 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 -
    • -
+

+ Some of the values listed above are not compatible with all + architecture and machine types, and if the value is missing altogeth= er, + libvirt will try to pick an appropriate default. In general, it's a + good idea to specify neither the target type nor the target model, + leave the task of choosing values up to libvirt, and don't change the + values afterward. +

=20

- 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 + Some of the types support configuring the guest-visible device + address as documented above. + For the relationship between serial ports and consoles, + see below.

=20 +
Console
+ 
 ...
 <devices>
+  <!-- Serial console -->
   <console type=3D'pty'>
-    <source path=3D'/dev/pts/4'/>
-    <target port=3D'0'/>
+    <source path=3D'/dev/pts/2'/>
+    <target type=3D'serial' port=3D'0'/>
   </console>
+</devices>
+...
=20 +
+...
   <!-- KVM virtio console -->
   <console type=3D'pty'>
     <source path=3D'/dev/pts/5'/>
@@ -6600,21 +6601,134 @@ qemu-kvm -net nic,model=3D? /dev/null
 </devices>
 ...
=20 +

+ The console element is used to represent interactive + serial consoles. Depending on the type of guest in use and the speci= fics + of the configuration, the console element might represe= nt + the same device as an existing serial element or a sepa= rate + device. +

+ +

+ A target subelement is supported and works the same way + as with the serial element + (see above for details); valid va= lues + for the type attribute are serial, + virtio, xen, lxc, + uml and openvz. The sclp and + sclplm values are supported for compatibility reasons b= ut + should not be used for new guests: use the sclpconsole + and sclplmconsole target models, respectively, with the + serial element instead. +

+ +

+ 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 differe= nce + 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 t= he + same limitation. +
    • +
+ +

+ A configuration such as: +

+ 
 ...
-<devices>
-  <!-- KVM S390 sclp console -->
+</devices>
+  <console type=3D'pty'>
+    <target type=3D'serial'/>
+  </console>
   <console type=3D'pty'>
-    <source path=3D'/dev/pts/1'/>
-    <target type=3D'sclp' port=3D'0'/>
+    <target type=3D'virtio'/>
   </console>
 </devices>
 ...
=20

- If the console is presented as a serial port, the target - element has the same attributes as for a serial port. There is usual= ly - only 1 console. + will work on any platform and will result in one emulated serial con= sole + 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=3D'pty'/>
+</devices>
+...
+ +
+...
+</devices>
+  <console type=3D'pty'/>
+</devices>
+...
+ +
+...
+</devices>
+  <serial type=3D'pty'/>
+  <console type=3D'pty'/>
+</devices>
+...
+ +

+ will be treated the same and will result in a single emulated serial + console being available to the guest.

=20
Channel
--=20 2.14.3 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list