docs: Fix XML schema handling of LUN address in hostdev tag

Defining a domain with a SCSI disk attached via a hostdev
tag and a source address unit value longer than two digits
causes an error when editing the domain with virsh edit,
even if no changes are made to the domain definition.
The error suggests invalid XML, somewhere:

  # virsh edit lmb_guest
  error: XML document failed to validate against schema:
  Unable to validate doc against /usr/local/share/libvirt/schemas/domain.rng
  Extra element devices in interleave
  Element domain failed to validate content

The virt-xml-validate tool fails with a similar error:

  # virt-xml-validate lmb_guest.xml
  Relax-NG validity error : Extra element devices in interleave
  lmb_guest.xml:17: element devices: Relax-NG validity error :
  Element domain failed to validate content
  lmb_guest.xml fails to validate

The hostdev tag requires a source address to be specified,
which includes bus, target, and unit address attributes.
According to the SCSI Architecture Model spec (section
4.9 of SAM-2), a LUN address is 64 bits and thus could be
up to 20 decimal digits long.  Unfortunately, the XML
schema limits this string to just two digits.  Similarly,
the target field can be up to 32 bits in length, which
would be 10 decimal digits.

  # lsscsi -xx
  [0:0:19:0x4022401100000000]  disk    IBM      2107900          3.44 /dev/sda
  # lsscsi
  [0:0:19:1074872354]disk    IBM      2107900          3.44  /dev/sda
  # cat lmb_guest.xml
  <domain type='kvm'>
    <name>lmb_guest</name>
    <memory unit='MiB'>1024</memory>
  ...trimmed...
    <devices>
      <controller type='scsi' model='virtio-scsi' index='0'/>
      <hostdev mode='subsystem' type='scsi'>
        <source>
          <adapter name='scsi_host0'/>
          <address bus='0' target='19' unit='1074872354'/>
        </source>
      </hostdev>
  ...trimmed...

Since the reference unit and target fields are used in
several places in the XML schema, create a separate one
specific for SCSI Logical Units that will permit the
greater length.  This permits both the validation utility
and the virsh edit command to succeed when a hostdev
tag is included.

Signed-off-by: Eric Farman <farman@linux.vnet.ibm.com>
Reviewed-by: Matthew Rosato <mjrosato@linux.vnet.ibm.com>
Reviewed-by: Stefan Zimmermann <stzi@linux.vnet.ibm.com>
Reviewed-by: Boris Fiuczynski <fiuczy@linux.vnet.ibm.com>

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 6a524dfdb9511890b95e742c55cf034f2fc6031a..16f7eae253d4f3b5e4c106c226c22977d3e2d557 100644 (file)
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -3283,7 +3283,14 @@
           </dd>
           <dt>scsi</dt>
           <dd>SCSI devices are described by both the <code>adapter</code>
-            and <code>address</code> elements.
+            and <code>address</code> elements. The <code>address</code>
+            element includes a <code>bus</code> attribute (a 2-digit bus
+            number), a <code>target</code> attribute (a 10-digit target
+            number), and a <code>unit</code> attribute (a 20-digit unit
+            number on the bus). Not all hypervisors support larger
+            <code>target</code> and <code>unit</code> values. It is up
+            to each hypervisor to determine the maximum value supported
+            for the adapter.
             <p>
             <span class="since">Since 1.2.8</span>, the <code>source</code>
             element of a SCSI device may contain the <code>protocol</code>

diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index ca3bcfcb8d94d0978ff2cca355f8d30f0d43102e..3014365bb5bd08639b48d993b1b1a0fff0110296 100644 (file)
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -3833,10 +3833,10 @@
       <ref name="driveBus"/>
     </attribute>
     <attribute name="target">
-      <ref name="driveTarget"/>
+      <ref name="driveSCSITarget"/>
     </attribute>
     <attribute name="unit">
-      <ref name="driveUnit"/>
+      <ref name="driveSCSIUnit"/>
     </attribute>
   </define>
   <define name="usbportaddress">
@@ -5152,11 +5152,21 @@
       <param name="pattern">[0-9]{1,2}</param>
     </data>
   </define>
+  <define name="driveSCSITarget">
+    <data type="string">
+      <param name="pattern">[0-9]{1,10}</param>
+    </data>
+  </define>
   <define name="driveUnit">
     <data type="string">
       <param name="pattern">[0-9]{1,2}</param>
     </data>
   </define>
+  <define name="driveSCSIUnit">
+    <data type="string">
+      <param name="pattern">[0-9]{1,20}</param>
+    </data>
+  </define>
   <define name="featureName">
     <data type="string">
       <param name='pattern'>[a-zA-Z0-9\-_\.]+</param>

diff --git a/tests/qemuxml2argvdata/qemuxml2argv-hostdev-scsi-large-unit.xml b/tests/qemuxml2argvdata/qemuxml2argv-hostdev-scsi-large-unit.xml
new file mode 100644 (file)
index 0000000..b5efb40
--- /dev/null
+++ b/tests/qemuxml2argvdata/qemuxml2argv-hostdev-scsi-large-unit.xml
@@ -0,0 +1,35 @@
+<domain type='qemu'>
+  <name>QEMUGuest2</name>
+  <uuid>c7a5fdbd-edaf-9466-926a-d65c16db1809</uuid>
+  <memory unit='KiB'>219100</memory>
+  <currentMemory unit='KiB'>219100</currentMemory>
+  <vcpu placement='static'>1</vcpu>
+  <os>
+    <type arch='i686' machine='pc'>hvm</type>
+    <boot dev='hd'/>
+  </os>
+  <clock offset='utc'/>
+  <on_poweroff>destroy</on_poweroff>
+  <on_reboot>restart</on_reboot>
+  <on_crash>destroy</on_crash>
+  <devices>
+    <emulator>/usr/bin/qemu</emulator>
+    <disk type='block' device='disk'>
+      <source dev='/dev/HostVG/QEMUGuest2'/>
+      <target dev='hda' bus='ide'/>
+      <address type='drive' controller='0' bus='0' target='0' unit='0'/>
+    </disk>
+    <controller type='scsi' index='0' model='virtio-scsi'/>
+    <controller type='usb' index='0'/>
+    <controller type='ide' index='0'/>
+    <controller type='pci' index='0' model='pci-root'/>
+    <hostdev mode='subsystem' type='scsi' managed='yes'>
+      <source>
+        <adapter name='scsi_host0'/>
+        <address bus='0' target='0' unit='1074872354'/>
+      </source>
+      <address type='drive' controller='0' bus='0' target='4' unit='8'/>
+    </hostdev>
+    <memballoon model='virtio'/>
+  </devices>
+</domain>

diff --git a/tests/qemuxml2xmltest.c b/tests/qemuxml2xmltest.c
index 3287ea37d5f4ea0ecc9e4162ea6a155ec248fe1a..711827dfe66d8e757bd66c77de652a5c6e3b86b8 100644 (file)
--- a/tests/qemuxml2xmltest.c
+++ b/tests/qemuxml2xmltest.c
@@ -577,6 +577,7 @@ mymain(void)
     DO_TEST("hostdev-scsi-rawio");
 
     DO_TEST_DIFFERENT("hostdev-scsi-autogen-address");
+    DO_TEST("hostdev-scsi-large-unit");
 
     DO_TEST("hostdev-scsi-lsi-iscsi");
     DO_TEST("hostdev-scsi-lsi-iscsi-auth");