doc: edit schema assert messages for clarity and grammar

Use DX names (acrn:title) instead of element names in messages. Add missing message in rdt_support.xsd (all asserts need an annotation with documentation for the error message that will be reported). Tracked-On: #7685 Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2022-06-03 13:02:14 -07:00 · 2022-06-03 13:02:14 -07:00 · 54e275c8bb
parent ecaecaf904
commit 54e275c8bb
8 changed files with 30 additions and 40 deletions
--- a/misc/config_tools/schema/checks/cpu_assignment.xsd
+++ b/misc/config_tools/schema/checks/cpu_assignment.xsd
@ -7,7 +7,7 @@

  <xs:assert test="every $vm in /acrn-config/vm[load_order != 'SERVICE_VM'] satisfies count($vm//cpu_affinity//pcpu_id) &gt;= 1">
    <xs:annotation acrn:severity="error" acrn:report-on="$vm//cpu_affinity">
-      <xs:documentation>VM "{$vm/name}" needs at least one vCPU.</xs:documentation>
+      <xs:documentation>VM "{$vm/name}" needs at least one vCPU assigned.</xs:documentation>
    </xs:annotation>
  </xs:assert>

@ -27,21 +27,21 @@
  <xs:assert test="every $pcpu in /acrn-config/vm[vm_type = 'RTVM']//cpu_affinity//pcpu_id satisfies
                   count(/acrn-config/vm[@id != $pcpu/ancestor::vm//companion_vmid ]//cpu_affinity[.//pcpu_id = $pcpu]) &lt;= 1">
    <xs:annotation acrn:severity="error" acrn:report-on="//vm//cpu_affinity[.//pcpu_id = $pcpu]">
-      <xs:documentation>Physical CPU {$pcpu} is assigned to real-time VM (RTVM) [{$pcpu/ancestor::vm/name}] and thus cannot be shared among multiple VMs. Look for, and probably remove, any affinity assignments to {$pcpu} in this VM's settings: {//vm[cpu_affinity//pcpu_id = $pcpu]/name}.</xs:documentation>
+      <xs:documentation>Physical CPU {$pcpu} is assigned to RTVM "[{$pcpu/ancestor::vm/name}]" and thus may not be shared among multiple VMs. Look for, and probably remove, any affinity assignments to CPU {$pcpu} in this VM {//vm[cpu_affinity//pcpu_id = $pcpu]/name} settings.</xs:documentation>
    </xs:annotation>
  </xs:assert>

  <xs:assert test="every $vm in /acrn-config/vm[load_order != 'SERVICE_VM'] satisfies
 	  count(/acrn-config/vm/cpu_affinity/pcpu/pcpu_id) > 0">
  <xs:annotation acrn:severity="error" acrn:report-on="//vm//cpu_affinity/pcpu">
-      <xs:documentation>The physical CPUs must be allocated to the VM "{$vm/name}".</xs:documentation>
+      <xs:documentation>At least one physical CPU must be allocated to VM "{$vm/name}".</xs:documentation>
    </xs:annotation>
  </xs:assert>

  <xs:assert test="every $vm in /acrn-config/vm[load_order != 'SERVICE_VM'] satisfies
                   count(distinct-values(processors//thread[cpu_id = $vm//cpu_affinity//pcpu_id]/core_type)) &lt;= 1">
    <xs:annotation acrn:severity="error" acrn:report-on="$vm//cpu_affinity">
-      <xs:documentation>The physical CPUs allocated to the VM "{$vm/name}" have both performance cores {processors//thread[cpu_id = $vm//cpu_affinity//pcpu_id and core_type = 'Core']/cpu_id} and efficient cores {processors//thread[cpu_id = $vm//cpu_affinity//pcpu_id and core_type = 'Atom']/cpu_id}, which is unsupported. Remove either all performance or all efficient cores from the CPU affinity.</xs:documentation>
+      <xs:documentation>The physical CPUs allocated to the VM "{$vm/name}" have both performance cores {processors//thread[cpu_id = $vm//cpu_affinity//pcpu_id and core_type = 'Core']/cpu_id} and efficiency cores {processors//thread[cpu_id = $vm//cpu_affinity//pcpu_id and core_type = 'Atom']/cpu_id}, which is unsupported. Remove either all performance or all efficiency cores from the CPU affinity.</xs:documentation>
    </xs:annotation>
  </xs:assert>

--- a/misc/config_tools/schema/checks/ivsh_memory.xsd
+++ b/misc/config_tools/schema/checks/ivsh_memory.xsd
@ -10,7 +10,7 @@
                  every $REGION_NAME in /acrn-config//IVSHMEM_REGION[IVSHMEM_VMS/IVSHMEM_VM/VM_NAME=$VM_NAME]/NAME satisfies
                  count(/acrn-config//IVSHMEM_REGION[NAME=$REGION_NAME]/IVSHMEM_VMS/IVSHMEM_VM[VM_NAME=$VM_NAME]) = 1">
    <xs:annotation acrn:severity="error" acrn:report-on="$REGION_NAME">
-      <xs:documentation>InterVM shared memory region name "{$REGION_NAME}" should be different for the same VM "{$VM_NAME}"</xs:documentation>
+        <xs:documentation>VM "{$VM_NAME}" may not be duplicated in the list of VMs that have access to the Inter-VM shared memory region "{$REGION_NAME}".</xs:documentation>
    </xs:annotation>
  </xs:assert>

--- a/misc/config_tools/schema/checks/passthrough_devices.xsd
+++ b/misc/config_tools/schema/checks/passthrough_devices.xsd
@ -8,7 +8,7 @@
  <xs:assert test="every $vm in /acrn-config/vm satisfies
                   not($vm//mmio_resources/TPM2 = 'y') or not($vm//mmio_resources/p2sb = 'y')">
    <xs:annotation acrn:severity="error" acrn:report-on="$vm//mmio_resources">
-      <xs:documentation>VM "{$vm/name}" is assigned both a TPM2 and P2SB (Primary-to-Sideband bridge), which is not a supported configuration. Remove one of these choices.</xs:documentation>
+      <xs:documentation>VM "{$vm/name}" is assigned both a TPM2 (Trusted Platform Module) and P2SB (Primary-to-Sideband Bridge), which is not a supported configuration. Remove one of these choices.</xs:documentation>
    </xs:annotation>
  </xs:assert>

--- a/misc/config_tools/schema/checks/rdt_support.xsd
+++ b/misc/config_tools/schema/checks/rdt_support.xsd
@ -7,7 +7,7 @@
                   then (//CDP_ENABLED = 'n' and //RDT_ENABLED = 'y')
                   else true()">
    <xs:annotation>
-      <xs:documentation>vCAT can be enabled only when RDT_ENABLED is 'y' and CDP_ENABLED is 'n'</xs:documentation>
+      <xs:documentation>Hypervisor Virtual Cache Allocation Technology may be enabled only when hypervisor Code and Data Prioritization is disabled.</xs:documentation>
    </xs:annotation>
  </xs:assert>

@ -15,19 +15,7 @@
                   then //RDT_ENABLED = 'y' and //VCAT_ENABLED = 'y'
                   else true()">
    <xs:annotation>
-      <xs:documentation>Per VM virtual_cat_support can be set only when RDT_ENABLED is 'y' and VCAT_ENABLED is 'y'.</xs:documentation>
-    </xs:annotation>
-  </xs:assert>
-
-  <xs:assert test="every $vm in vm satisfies
-                  (
-                    if (//RDT_ENABLED = 'y' and //VCAT_ENABLED = 'y' and $vm/virtual_cat_support[text() = 'y'])
-                    then count($vm/clos/vcpu_clos) > 1
-                    else true()
-                  )
-                  ">
-    <xs:annotation>
-      <xs:documentation>For a vCAT VM, number of clos/vcpu_clos elements must be greater than 1!</xs:documentation>
+      <xs:documentation>VM Virtual Cache Allocation Technology may be enabled only when hypervisor Virtual Cache Allocation Technology is enabled.</xs:documentation>
    </xs:annotation>
  </xs:assert>

@ -35,7 +23,7 @@
                   then count(vm[virtual_cat_support[text() = 'y'] and count(clos/vcpu_clos[. = 0])]) = 0
                   else true()">
    <xs:annotation>
-      <xs:documentation>For a vCAT VM, vcpu_clos cannot be set to CLOSID 0, CLOSID 0 is reserved to be used by hypervisor</xs:documentation>
+      <xs:documentation>CLOSID 0 is reserved for the hypervisor and may not be used as a vcpu_clos by a VM.</xs:documentation>
    </xs:annotation>
  </xs:assert>

@ -47,7 +35,7 @@
                  )
                  ">
    <xs:annotation>
-      <xs:documentation>For a vCAT VM, each clos/vcpu_clos must be less than L2/L3 COS_MAX!</xs:documentation>
+      <xs:documentation>Each clos/vcpu_clos must be less than L2/L3 CLOS_MAX.</xs:documentation>
    </xs:annotation>
  </xs:assert>

@ -59,7 +47,7 @@
                  )
                  ">
    <xs:annotation>
-      <xs:documentation>For a vCAT VM, its clos/vcpu_clos elements cannot contain duplicate values</xs:documentation>
+      <xs:documentation>A VM's clos/vcpu_clos settings may not contain duplicate values.</xs:documentation>
    </xs:annotation>
  </xs:assert>

@ -71,31 +59,33 @@
                  )
                  ">
    <xs:annotation>
-      <xs:documentation>if RDT_ENABLED is 'y', there should not be any CLOS IDs overlap between a vCAT VM and any other VMs</xs:documentation>
+      <xs:documentation>When Virtual Cache Allocation Technology is enabled, CLOS IDs may not overlap between any VMs.</xs:documentation>
    </xs:annotation>
  </xs:assert>

  <xs:assert test="every $vm in //vm satisfies $vm//load_order != 'SERVICE_VM' or count($vm//lapic_passthrough[text() = 'y']) = 0 or count(//nested_virtualization_support[text() = 'y']) > 0">
    <xs:annotation>
-      <xs:documentation>Service VM cannot use LAPIC passthrough unless GUEST_FLAG_NVMX_ENABLED is set.</xs:documentation>
+      <xs:documentation>The Service VM may not use LAPIC passthrough unless hypervisor Nested Virtualization is enabled.</xs:documentation>
    </xs:annotation>
  </xs:assert>

-  <xs:assert test="not (//hv//RDT/RDT_ENABLED = 'y' and //hv//SSRAM/SSRAM_ENABLED = 'y')"/>
+  <xs:assert test="not (//hv//RDT/RDT_ENABLED = 'y' and //hv//SSRAM/SSRAM_ENABLED = 'y')">
+    <xs:annotation>
+      <xs:documentation>The hypervisor Intel Resource Director Technology and Software SRAM settings may not be enabled at the same time.</xs:documentation>
+    </xs:annotation>
+  </xs:assert>

  <xs:assert test="hv//SSRAM_ENABLED = 'n' or empty(vm[load_order ='PRE_LAUNCHED_VM' and vm_type='RTVM']) or
 		   every $cap in caches/cache[@level=3]/capability[@id='Software SRAM'] satisfies
 		   (compare($cap/end, '0x80000000') &lt; 0 or compare($cap/start, '0xf8000000') &gt;= 0)">
    <xs:annotation acrn:severity="warning">
-      <xs:documentation>The physical software SRAM region shall not overlap with pre-defined regions in guest.
+      <xs:documentation>The physical software SRAM region may not overlap with pre-defined regions in any VM.

 When a pre-launched RTVM is enabled, the physical software SRAM is allocated to it at the same guest physical
 address. Thus it is assumed that the software SRAM region does not overlap with any pre-defined region in the
-pre-launched VM, such as the guest PCI hole which resides at 2G - 3.5G.
-
-This error cannot be fixed by tweaking the configurations. Report to _GitHub:
-https://github.com/projectacrn/acrn-hypervisor/issues if you meet this.</xs:documentation>
+pre-launched VM, such as the guest PCI hole which resides at 2GB - 3.5GB.

+This error cannot be fixed by adjusting the configuration. Report a `GitHub issue &lt;https://github.com/projectacrn/acrn-hypervisor/issues&gt;`_ if you receive this error.</xs:documentation>
    </xs:annotation>
  </xs:assert>

--- a/misc/config_tools/schema/checks/vbdf_assignment.xsd
+++ b/misc/config_tools/schema/checks/vbdf_assignment.xsd
@ -10,7 +10,7 @@
 		   every $vbdf in $root/hv//vuart_connection[type='pci']/endpoint[vm_name=$vm/name]/vbdf/text() | $root/hv//IVSHMEM_VM[VM_NAME=$vm/name]/VBDF/text() satisfies
 		   count($root/hv//vuart_connection[type='pci']/endpoint[vm_name=$vm/name and vbdf=$vbdf] | $root/hv//IVSHMEM_VM[VM_NAME=$vm/name and VBDF=$vbdf]) = 1">
    <xs:annotation acrn:severity="error" acrn:report-on="$root/hv//vuart_connection[type='pci']/endpoint[vm_name=$vm/name and vbdf=$vbdf] | $root/hv//IVSHMEM_VM[VM_NAME=$vm/name and VBDF=$vbdf]">
-      <xs:documentation>VM "{$vm/name}" contains multiple virtual UART controllers and/or IVSHMEM interfaces using BDF {$vbdf}. Adjust the BDF of those devices.</xs:documentation>
+      <xs:documentation>VM "{$vm/name}" contains multiple virtual UART controllers or IVSHMEM interfaces using BDF {$vbdf}. Adjust the BDF of those devices to be unique.</xs:documentation>
    </xs:annotation>
  </xs:assert>

--- a/misc/config_tools/schema/checks/virtio_devices.xsd
+++ b/misc/config_tools/schema/checks/virtio_devices.xsd
@ -10,7 +10,7 @@
                   count(//virtio_devices/vsock[text()=$vsock]) = 1
                   ">
    <xs:annotation acrn:severity="error" acrn:report-on="$vm">
-      <xs:documentation>"{$vm/name}" repeats a vsock CID assignment: {$vsock}, either with this VM or with other VMs. Remove the duplicates.</xs:documentation>
+      <xs:documentation>VM "{$vm/name}" repeats a vsock CID assignment: {$vsock}, used in this VM or another VM. Make all vsock CID values unique.</xs:documentation>
    </xs:annotation>
  </xs:assert>

--- a/misc/config_tools/schema/checks/vm_types.xsd
+++ b/misc/config_tools/schema/checks/vm_types.xsd
@ -7,7 +7,7 @@

  <xs:assert test="count(/acrn-config/vm[.//load_order = 'SERVICE_VM']) &lt; 2">
    <xs:annotation acrn:severity="error" acrn:report-on="//vm[.//load_order = 'SERVICE_VM']">
-      <xs:documentation>There can be at most one service VM, but more than one was configured. Verify there is only one VM with vm_type set to SERVICE_VM. </xs:documentation>
+      <xs:documentation>There may be at most one Service VM, but more than one was configured. Verify only one VM's VM type is set to SERVICE_VM. </xs:documentation>
    </xs:annotation>
  </xs:assert>

@ -29,13 +29,13 @@

  <xs:assert test="count(vm[load_order = 'PRE_LAUNCHED_VM' and vm_type = 'RTVM']) &lt;= 1">
    <xs:annotation acrn:severity="warning" acrn:report-on="//vm[load_order = 'PRE_LAUNCHED_VM']/vm_type[text() = 'RTVM']">
-      <xs:documentation>Multiple pre-launched VMs {//vm[load_order = 'PRE_LAUNCHED_VM' and vm_type = 'RTVM']/name} are defined as RT VMs, but ACRN supports at most one pre-launched RT VM in one scenario. Adjust the VM types of those VMs to STANDARD_VM to fix this.</xs:documentation>
+      <xs:documentation>ACRN supports at most one pre-launched RTVM. Multiple pre-launched VMs {//vm[load_order = 'PRE_LAUNCHED_VM' and vm_type = 'RTVM']/name} are defined as RTVMs. Adjust the VM type of these VMs to Standard to fix this.</xs:documentation>
    </xs:annotation>
  </xs:assert>

  <xs:assert test="count(distinct-values(vm[vm_type = 'RTVM']/load_order)) &lt;= 1">
    <xs:annotation acrn:severity="warning" acrn:report-on="//vm/vm_type[text() = 'RTVM']">
-      <xs:documentation>Pre-launched RT VM(s) {//vm[load_order = 'PRE_LAUNCHED_VM' and vm_type = 'RTVM']/name} and post-launched RT VMs {//vm[load_order = 'POST_LAUNCHED_VM' and vm_type = 'RTVM']/name} cannot coexist. Adjust the VM types of those VMs to STANDARD_VM to fix this.</xs:documentation>
+      <xs:documentation>Pre-launched RTVM(s) {//vm[load_order = 'PRE_LAUNCHED_VM' and vm_type = 'RTVM']/name} and post-launched RTVMs {//vm[load_order = 'POST_LAUNCHED_VM' and vm_type = 'RTVM']/name} may not coexist. Adjust the VM type of these VMs to Standard to fix this.</xs:documentation>
    </xs:annotation>
  </xs:assert>

--- a/misc/config_tools/schema/checks/vuart_config.xsd
+++ b/misc/config_tools/schema/checks/vuart_config.xsd
@ -10,14 +10,14 @@
                   every $vm_name in $vuart_connection/endpoint/vm_name/text() satisfies
                   count($vuart_connection/endpoint[./vm_name/text()=$vm_name]) = 1">
    <xs:annotation acrn:severity="error" acrn:report-on="$vuart_connection/endpoint">
-      <xs:documentation>VM "{$vm_name}" can't connected to itself</xs:documentation>
+      <xs:documentation>The vUART configuration of VM "{$vm_name}" may not connect to itself.</xs:documentation>
    </xs:annotation>
  </xs:assert>

  <xs:assert test="every $io_port in /acrn-config//endpoint/io_port satisfies
                   count(//endpoint[./vm_name=$io_port/ancestor::endpoint/vm_name and io_port=$io_port]) = 1">
    <xs:annotation acrn:severity="error" acrn:report-on="$io_port">
-      <xs:documentation>VM "{$io_port/ancestor::endpoint/vm_name}" use duplicate "{$io_port}"</xs:documentation>
+      <xs:documentation>VM "{$io_port/ancestor::endpoint/vm_name}" may not duplicate use of port "{$io_port}."</xs:documentation>
    </xs:annotation>
  </xs:assert>

@ -32,7 +32,7 @@
                   then count(//endpoint[./vm_name=$console_port/ancestor::vm/name and io_port='0x2E8']) &lt; 1
                   else true()">
    <xs:annotation acrn:severity="error" acrn:report-on="$console_port">
-      <xs:documentation>VM "{$console_port/ancestor::vm/name}" use duplicate "{$console_port}"</xs:documentation>
+      <xs:documentation>VM "{$console_port/ancestor::vm/name}" may not duplicate use of console "{$console_port}."</xs:documentation>
    </xs:annotation>
  </xs:assert>