[libvirt] [PATCHv4 1/5] S390: Documentation for CCW address type

[Viktor Mihajlovski]

The native bus for s390 I/O is called CCW (channel command word).
As QEMU has added basic support for the CCW bus, i.e. the
ability to assign CCW devnos (bus addresses) to devices.
Domains with the new machine type s390-ccw-virtio can use the
CCW bus. Currently QEMU will only allow to define virtio
devices on the CCW bus.
Here we add the new machine type and the new device address to the
schema definition and add a new paragraph to the domain XML
documentation.

Signed-off-by: Viktor Mihajlovski <mihajlov at linux.vnet.ibm.com>
---
V2 Changes
 - replace single devno attribute with cssid, ssid, schid triple
   in documentation section
 - add new data ranges for cssid, ssid and schid to domain schema

V4 Changes
 - replace attribute 'schid' with 'devno', as this is the technically
   correct term for a user-configurable device bus id.

 docs/formatdomain.html.in     |   14 +++++++++++
 docs/schemas/domaincommon.rng |   52 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 4cafc92..35b47f2 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -2018,6 +2018,20 @@
         of the starting register).  <span class="since">Since
         0.9.9.</span>
       </dd>
+      <dt><code>type='ccw'</code></dt>
+      <dd>s390 guests with a <code>machine</code> value of
+        s390-ccw-virtio use the native CCW bus for I/O devices.
+        CCW bus addresses have the following additional attributes:
+        <code>cssid</code> (a hex value between 0 and 0xfe, inclusive),
+        <code>ssid</code> (a value between 0 and 3, inclusive) and
+        <code>devno</code> (a hex value between 0 and 0xffff, inclusive).
+        Partially specified bus addresses are not allowed.
+        If omitted, libvirt will assign a free bus address with
+        cssid=0xfe and ssid=0. Virtio devices for s390 must have their
+        cssid set to 0xfe in order to be recognized by the guest
+        operating system.
+        <span class="since">Since 1.0.4</span>
+      </dd>
     </dl>
 
     <h4><a name="elementsControllers">Controllers</a></h4>
diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index 4b60885..c054ec7 100644
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -401,7 +401,10 @@
       <optional>
         <attribute name="machine">
           <choice>
+            <value>s390</value>
             <value>s390-virtio</value>
+            <value>s390-ccw</value>
+            <value>s390-ccw-virtio</value>
           </choice>
         </attribute>
       </optional>
@@ -3037,6 +3040,19 @@
       </attribute>
     </optional>
   </define>
+  <define name="ccwaddress">
+    <optional>
+      <attribute name="cssid">
+        <ref name="ccwCssidRange"/>
+      </attribute>
+      <attribute name="ssid">
+        <ref name="ccwSsidRange"/>
+      </attribute>
+      <attribute name="devno">
+        <ref name="ccwDevnoRange"/>
+      </attribute>
+    </optional>
+  </define>
   <define name="driveaddress">
     <optional>
       <attribute name="controller">
@@ -3470,6 +3486,12 @@
           </attribute>
           <ref name="spaprvioaddress"/>
         </group>
+        <group>
+          <attribute name="type">
+            <value>ccw</value>
+          </attribute>
+          <ref name="ccwaddress"/>
+        </group>
       </choice>
     </element>
   </define>
@@ -3891,4 +3913,34 @@
     </element>
     <empty/>
   </define>
+  <define name="ccwCssidRange">
+    <choice>
+      <data type="string">
+        <param name="pattern">0x[0-9a-eA-E][0-9a-fA-F]?</param>
+      </data>
+      <data type="string">
+        <param name="pattern">0x[fF][0-9a-eA-E]?</param>
+      </data>
+      <data type="int">
+        <param name="minInclusive">0</param>
+        <param name="maxInclusive">254</param>
+      </data>
+    </choice>
+  </define>
+  <define name="ccwSsidRange">
+    <data type="string">
+      <param name="pattern">(0x)?[0-3]</param>
+    </data>
+  </define>
+  <define name="ccwDevnoRange">
+    <choice>
+      <data type="string">
+        <param name="pattern">0x[0-9a-fA-F]{1,4}</param>
+      </data>
+      <data type="int">
+        <param name="minInclusive">0</param>
+        <param name="maxInclusive">65535</param>
+      </data>
+    </choice>
+  </define>
 </grammar>
-- 
1.7.9.5