doc: update schema type documentation

Add documentation for enumerated types and value restrictions so it shows up in the option documention. Also add additional acrn:title annotations. Tracked-On: #5692 Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2025-08-18 08:11:07 +00:00 · 2022-04-20 13:32:20 -07:00 · 2022-04-20 13:32:20 -07:00 · 410d317fe4
commit 410d317fe4
parent 98f7dfd131
3 changed files with 51 additions and 12 deletions
--- a/misc/config_tools/schema/VMtypes.xsd
+++ b/misc/config_tools/schema/VMtypes.xsd
@ -7,8 +7,8 @@
  <xs:annotation>
    <xs:documentation>Current supported VM types are:

- ``PRE_LAUNCHED_VM`` pre-launched VM
 - ``SERVICE_VM`` Service VM
+- ``PRE_LAUNCHED_VM`` pre-launched VM
 - ``POST_LAUNCHED_VM`` post-launched VM</xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:string">
@ -46,8 +46,7 @@
  <xs:sequence>
    <xs:element name="pcpu_id" type="xs:integer" default="2" minOccurs="0" maxOccurs="unbounded">
      <xs:annotation>
-        <xs:documentation>A pCPU that this VM's vCPU is allowed to pin
-to.</xs:documentation>
+        <xs:documentation>A pCPU that this VM's vCPU is allowed to pin to.</xs:documentation>
      </xs:annotation>
    </xs:element>
  </xs:sequence>
@ -180,7 +179,7 @@ CLOSID 0 and the second is mapped to virtual CLOSID 1, etc.</xs:documentation>

 <xs:simpleType name="VuartType">
  <xs:annotation>
-    <xs:documentation>vCOM type</xs:documentation>
+    <xs:documentation>A string with value: ``legacy`` or ``pci``.</xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:enumeration value="legacy">
@ -214,7 +213,11 @@ CLOSID 0 and the second is mapped to virtual CLOSID 1, etc.</xs:documentation>

 <xs:complexType name="VuartConnectionType">
  <xs:sequence>
-    <xs:element name="name" type="xs:string" />
+      <xs:element name="name" type="xs:string">
+          <xs:annotation>
+        <xs:documentation>Specify the vUART name.</xs:documentation>
+      </xs:annotation>
+    </xs:element>
    <xs:element name="type" type="VuartType" default="legacy">
      <xs:annotation acrn:title="Type">
        <xs:documentation>Select the communication virtual UART (vUART) type.</xs:documentation>
@ -257,6 +260,9 @@ CLOSID 0 and the second is mapped to virtual CLOSID 1, etc.</xs:documentation>
 </xs:complexType>

 <xs:simpleType name="VirtioNetworkFrameworkType">
+  <xs:annotation>
+       <xs:documentation>A string with value: ``Kernel based (Virtual Host)`` or ``User space based (VBSU)``.</xs:documentation>
+  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:enumeration value="Kernel based (Virtual Host)" />
    <xs:enumeration value="User space based (VBSU)" />
@ -275,6 +281,9 @@ CLOSID 0 and the second is mapped to virtual CLOSID 1, etc.</xs:documentation>
        <xs:documentation>Specify the network interface name that will appear in the Service VM. Use the `ip a` command in the Service VM to display the network interface names.</xs:documentation>
      </xs:annotation>
      <xs:simpleType>
+  <xs:annotation>
+       <xs:documentation>A string of letters, digits, ``_``, or ``-``.</xs:documentation>
+  </xs:annotation>
        <xs:restriction base="xs:string">
          <xs:pattern value="[a-zA-Z0-9_\-]+" />
        </xs:restriction>
@ -284,6 +293,9 @@ CLOSID 0 and the second is mapped to virtual CLOSID 1, etc.</xs:documentation>
 </xs:complexType>

 <xs:simpleType name="VirtioConsoleUseType">
+  <xs:annotation>
+       <xs:documentation>A string with value: ``Virtio console`` or ``Virtio serial port``</xs:documentation>
+  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:enumeration value="Virtio console" />
    <xs:enumeration value="Virtio serial port" />
@ -291,6 +303,9 @@ CLOSID 0 and the second is mapped to virtual CLOSID 1, etc.</xs:documentation>
 </xs:simpleType>

 <xs:simpleType name="VirtioConsoleBackendType">
+  <xs:annotation>
+       <xs:documentation>A string with value: ``pty``, ``stdio``, or ``file``.</xs:documentation>
+  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:enumeration value="pty" />
    <xs:enumeration value="stdio" />
@ -350,6 +365,9 @@ device file when user config it as virtio serial port, which can be read and wri
        <xs:documentation>Specifying unique identifier to distinguish same devices in guest.</xs:documentation>
      </xs:annotation>
      <xs:simpleType>
+         <xs:annotation>
+              <xs:documentation>A string with letters, digits, ``_``, or ``-``.</xs:documentation>
+         </xs:annotation>
        <xs:restriction base="xs:string">
          <xs:pattern value="[a-zA-Z0-9_\-]*" />
        </xs:restriction>
--- a/misc/config_tools/schema/config.xsd
+++ b/misc/config_tools/schema/config.xsd
@ -298,7 +298,7 @@ Refer to :ref:`vuart_config` for detailed vUART settings.</xs:documentation>
        </xs:annotation>
      <xs:simpleType>
        <xs:annotation>
-          <xs:documentation>string from 1 to 32 characters long.</xs:documentation>
+          <xs:documentation>A string from 1 to 32 characters long (with no spaces).</xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:string">
          <xs:minLength value="1" />
@ -474,14 +474,14 @@ mouse, and tablet.  It sends Linux input layer events over virtio.</xs:documenta
 <xs:complexType name="ACRNConfigType">
  <xs:all>
    <xs:element name="hv" type="HVConfigType">
-      <xs:annotation>
+      <xs:annotation acrn:title="Hypervisor Options">
        <xs:documentation>The hypervisor configuration defines a working scenario and target
 board by configuring the hypervisor image features and capabilities such as
 setting up the log and the serial port.</xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="vm" maxOccurs="unbounded">
-      <xs:annotation>
+      <xs:annotation acrn:title="Virtual Machine Options">
        <xs:documentation>VM configuration includes **scenario-based** VM configuration
 information that is used to describe the characteristics and attributes for
 all VMs in a user scenario. It also includes **launch script-based** VM
--- a/misc/config_tools/schema/types.xsd
+++ b/misc/config_tools/schema/types.xsd
@ -14,6 +14,9 @@
 </xs:simpleType>

 <xs:simpleType name="EnablementType">
+  <xs:annotation>
+    <xs:documentation>A string with value: ``Enable`` or ``Disable``.</xs:documentation>
+  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:enumeration value="Enable" />
    <xs:enumeration value="Disable" />
@ -22,7 +25,7 @@

 <xs:simpleType name="HexFormat">
  <xs:annotation>
-    <xs:documentation>An Integer value in hexadecimal format.</xs:documentation>
+    <xs:documentation>An Integer value in hexadecimal format (with a leading ``0x``).</xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:pattern value="0[Xx][0-9A-Fa-f]+|0" />
@ -37,7 +40,7 @@

 <xs:simpleType name="BuildType">
  <xs:annotation>
-    <xs:documentation>A string that indicates the build type of the hypervisor.</xs:documentation>
+    <xs:documentation>A string with value ``Release`` or ``Debug`` that indicates the build type of the hypervisor.</xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:enumeration value="release">
@ -126,14 +129,14 @@ higher value (lower severity) are discarded.</xs:documentation>

 <xs:simpleType name="SchedulerType">
  <xs:annotation>
-    <xs:documentation>Options:
+    <xs:documentation>A string specifying the scheduling option:

 - ``No-Operation (NOOP)``: The No-Operation (NOOP) scheduler means there is a
  strict one-to-one mapping between vCPUs and pCPUs.
 - ``Borrowed Virtual Time``: The Borrowed Virtual Time (BVT) scheduler is a
  virtual time-based scheduling algorithm. It dispatches the runnable thread with the
  earliest effective virtual time.
- ``Priority Based Scheduling``: The priority based scheduler supports vCPU scheduling based on their pre-configured priorities.
+- ``Priority Based Scheduling``: The priority based scheduler supports vCPU scheduling based on pre-configured priorities.

 Read more about the available scheduling options in :ref:`cpu_sharing`.</xs:documentation>
  </xs:annotation>
@ -181,18 +184,27 @@ Read more about the available scheduling options in :ref:`cpu_sharing`.</xs:docu
 </xs:simpleType>

 <xs:simpleType name="VMNameType">
+  <xs:annotation>
+    <xs:documentation>A string of up to 15 letters, digits, ``_``, or ``-``.</xs:documentation>
+  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:pattern value="([a-zA-Z0-9_\-]){1,15}" />
  </xs:restriction>
 </xs:simpleType>

 <xs:simpleType name="VBDFType">
+  <xs:annotation>
+    <xs:documentation>A string with up to two hex digits, a ``:``, two hex digits, a ``.``, and one digit between 0-7.</xs:documentation>
+  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:pattern value="[0-9A-Fa-f]{1,2}:[0-1][0-9A-Fa-f].[0-7]" />
  </xs:restriction>
 </xs:simpleType>

 <xs:simpleType name="ProviderType">
+  <xs:annotation>
+    <xs:documentation>A string with value ``Hypervisor`` or ``Device Model``.</xs:documentation>
+  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:enumeration value="Hypervisor" />
    <xs:enumeration value="Device Model" />
@ -215,6 +227,9 @@ Read more about the available scheduling options in :ref:`cpu_sharing`.</xs:docu
 </xs:complexType>

 <xs:complexType name="IVSHMEMVMS">
+  <xs:annotation>
+    <xs:documentation>A sequence of Shared VM names and their Virtual BDF values.</xs:documentation>
+  </xs:annotation>
  <xs:sequence>
   <xs:element name="IVSHMEM_VM" type="IVSHMEMVM" maxOccurs="unbounded">
     <xs:annotation>
@ -225,6 +240,9 @@ Read more about the available scheduling options in :ref:`cpu_sharing`.</xs:docu
 </xs:complexType>

 <xs:simpleType name="IVSHMEMSize">
+  <xs:annotation>
+    <xs:documentation>An Integer with value a power of 2 between 2 and 512.</xs:documentation>
+  </xs:annotation>
  <xs:restriction base="xs:integer">
    <xs:enumeration value="2" />
    <xs:enumeration value="4" />
@ -245,6 +263,9 @@ Read more about the available scheduling options in :ref:`cpu_sharing`.</xs:docu
        <xs:documentation>Name of the shared memory region.</xs:documentation>
      </xs:annotation>
      <xs:simpleType>
+  <xs:annotation>
+    <xs:documentation>A string with no spaces.</xs:documentation>
+  </xs:annotation>
 	<xs:restriction base="xs:string">
 	  <xs:pattern value="\w+" />
 	</xs:restriction>