From 54e275c8bb4bea9a146f80332f4cf3eb79c47c0a Mon Sep 17 00:00:00 2001
From: "David B. Kinder" <david.b.kinder@intel.com>
Date: Fri, 3 Jun 2022 13:02:14 -0700
Subject: [PATCH] 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>
---
 .../schema/checks/cpu_assignment.xsd          |  8 ++--
 .../schema/checks/ivsh_memory.xsd             |  2 +-
 .../schema/checks/passthrough_devices.xsd     |  2 +-
 .../schema/checks/rdt_support.xsd             | 42 +++++++------------
 .../schema/checks/vbdf_assignment.xsd         |  2 +-
 .../schema/checks/virtio_devices.xsd          |  2 +-
 misc/config_tools/schema/checks/vm_types.xsd  |  6 +--
 .../schema/checks/vuart_config.xsd            |  6 +--
 8 files changed, 30 insertions(+), 40 deletions(-)

diff --git a/misc/config_tools/schema/checks/cpu_assignment.xsd b/misc/config_tools/schema/checks/cpu_assignment.xsd
index ff88b4092..0af953674 100644
--- 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>
 
diff --git a/misc/config_tools/schema/checks/ivsh_memory.xsd b/misc/config_tools/schema/checks/ivsh_memory.xsd
index 33e2bbd6a..ce966665b 100644
--- 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>
 
diff --git a/misc/config_tools/schema/checks/passthrough_devices.xsd b/misc/config_tools/schema/checks/passthrough_devices.xsd
index 3d9e21039..c495ebbe4 100644
--- 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>
 
diff --git a/misc/config_tools/schema/checks/rdt_support.xsd b/misc/config_tools/schema/checks/rdt_support.xsd
index 9288d1bef..38c045471 100644
--- 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 RT VM is enabled, the physical software SRAM is allocated to it at the same guest physical
+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>
 
diff --git a/misc/config_tools/schema/checks/vbdf_assignment.xsd b/misc/config_tools/schema/checks/vbdf_assignment.xsd
index 45a65945b..fde14c2b7 100644
--- 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>
 
diff --git a/misc/config_tools/schema/checks/virtio_devices.xsd b/misc/config_tools/schema/checks/virtio_devices.xsd
index 87556cc24..b7eac7d45 100644
--- 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>
 
diff --git a/misc/config_tools/schema/checks/vm_types.xsd b/misc/config_tools/schema/checks/vm_types.xsd
index 9815522d6..fb54fb2fa 100644
--- 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>
 
diff --git a/misc/config_tools/schema/checks/vuart_config.xsd b/misc/config_tools/schema/checks/vuart_config.xsd
index c208176b2..2ecbb5a4b 100644
--- 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>