doc: cleanup xsd-derived config doc text

Start cleaning up formatting and content layout issues in the
xsd-derived configuration option documentation.  Includes adding
documentation for unnamed embedded simple types within an element (and
updates to the XSLT transformation to display these), cleanup of element
and type documentation, typos and description clarity.

Improved xsdl translation to automatically include default values and if
an option is optional (instead of manually documenting this in the
description text).

Tracked-On: #5692

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

doc/reference/config-options.rst

@@ -7,6 +7,8 @@ As explained in :ref:`acrn_configuration_tool`, ACRN scenarios define
 the hypervisor (hv) and VM settings for the execution environment of an
 ACRN-based application.  This document describes these option settings.
 
+.. rst-class:: rst-columns3
+
 .. contents::
    :local:
    :depth: 2

doc/scripts/configdoc.xsl

@@ -4,10 +4,10 @@
     version="1.0"
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     xmlns:xs="http://www.w3.org/2001/XMLSchema">
-  <xsl:output method="text" />
+  <xsl:output method="text"/>
 
-  <xsl:variable name="newline" select="'&#xa;'" />
+  <xsl:variable name="newline" select="'&#xa;'"/>
-  <xsl:variable name="section_adornment" select="'#*=-%+@`'" />
+  <xsl:variable name="section_adornment" select="'#*=-%+@`'"/>
 
   <!--
       Visitors of XSD elements
@@ -16,27 +16,27 @@
   <xsl:template match="/xs:schema">
 
     <xsl:apply-templates select="xs:complexType[@name='ACRNConfigType']">
-      <xsl:with-param name="level" select="2" />
+      <xsl:with-param name="level" select="2"/>
-      <xsl:with-param name="prefix" select="''" />
+      <xsl:with-param name="prefix" select="''"/>
     </xsl:apply-templates>
 
   </xsl:template>
 
   <xsl:template match="xs:complexType[@name='ACRNConfigType']">
-    <xsl:param name="level" />
+    <xsl:param name="level"/>
-    <xsl:param name="prefix" />
+    <xsl:param name="prefix"/>
 
     <xsl:apply-templates select="descendant::xs:element">
-      <xsl:with-param name="level" select="$level" />
+      <xsl:with-param name="level" select="$level"/>
-      <xsl:with-param name="prefix" select="$prefix" />
+      <xsl:with-param name="prefix" select="$prefix"/>
     </xsl:apply-templates>
   </xsl:template>
 
   <xsl:template match="xs:element">
-    <xsl:param name="level" />
+    <xsl:param name="level"/>
-    <xsl:param name="prefix" />
+    <xsl:param name="prefix"/>
 
-    <xsl:variable name="ty" select="@type" />
+    <xsl:variable name="ty" select="@type"/>
 
     <!-- Only visit elements having complex types. Those having simple types are
          described as an option.. -->
@@ -50,28 +50,29 @@
        <!-- The section header -->
        <xsl:if test="$level &lt;= 4">
          <xsl:call-template name="section-header">
-           <xsl:with-param name="title" select="concat($prefix, @name)" />
+           <xsl:with-param name="title" select="concat($prefix, @name)"/>
-           <xsl:with-param name="label" select="concat($prefix, @name)" />
+           <xsl:with-param name="label" select="concat($prefix, @name)"/>
-           <xsl:with-param name="level" select="$level" />
+           <xsl:with-param name="level" select="$level"/>
          </xsl:call-template>
 
          <!-- Description of this menu / entry -->
          <xsl:call-template name="print-annotation" >
-            <xsl:with-param name="indent" select="''" />
+            <xsl:with-param name="indent" select="''"/>
          </xsl:call-template>
-         <xsl:value-of select="$newline" />
+
+         <xsl:value-of select="$newline"/>
 <!-- Occurence requirements (removed, but save just in case)
          <xsl:call-template name="print-occurs">
-           <xsl:with-param name="name" select="@name" />
+           <xsl:with-param name="name" select="@name"/>
          </xsl:call-template>
 -->
-          <xsl:value-of select="$newline" />
+          <xsl:value-of select="$newline"/>
        </xsl:if>
 
        <!-- Visit the complex type to generate menus and/or entries -->
        <xsl:apply-templates select="//xs:complexType[@name=$ty]">
-         <xsl:with-param name="level" select="$level" />
+         <xsl:with-param name="level" select="$level"/>
-         <xsl:with-param name="name" select="concat($prefix, @name)" />
+         <xsl:with-param name="name" select="concat($prefix, @name)"/>
        </xsl:apply-templates>
 <!-- for top level sections (level 2) put a begin/end comment for
      potential use in rst include directives -->
@@ -81,66 +82,68 @@
       </xsl:when>
       <xsl:otherwise>
        <xsl:call-template name="option-header">
-         <xsl:with-param name="label" select="concat($prefix, @name)" />
+         <xsl:with-param name="label" select="concat($prefix, @name)"/>
        </xsl:call-template>
-       <xsl:value-of select="$newline" />
+       <xsl:value-of select="$newline"/>
        <!-- Print the description, type, and occurrence requirements -->
        <xsl:text>   - </xsl:text>
        <xsl:call-template name="print-annotation" >
-          <xsl:with-param name="indent" select="'     '" />
+          <xsl:with-param name="indent" select="'     '"/>
        </xsl:call-template>
        <xsl:choose>
          <xsl:when test="//xs:simpleType[@name=$ty]">
-           <xsl:apply-templates select="//xs:simpleType[@name=$ty]" />
+           <xsl:apply-templates select="//xs:simpleType[@name=$ty]"/>
          </xsl:when>
          <xsl:when test="starts-with($ty, 'xs:')">
            <xsl:text>   - </xsl:text>
-           <xsl:value-of select="substring($ty, 4)" />
+           <xsl:value-of select="substring($ty, 4)"/>
-           <xsl:value-of select="$newline" />
+           <xsl:value-of select="$newline"/>
          </xsl:when>
          <xsl:otherwise>
-           <xsl:text>   - </xsl:text>
+<!-- element doesn't have a named type, check for an unnamed simpleType child -->
-           <xsl:value-of select="$ty" />
+           <xsl:apply-templates select="descendant::xs:simpleType">
-           <xsl:value-of select="$newline" />
+             <xsl:with-param name="level" select="$level"/>
+             <xsl:with-param name="prefix" select="''"/>
+           </xsl:apply-templates>
          </xsl:otherwise>
        </xsl:choose>
 <!-- removing occurs info for now
        <xsl:text>   - </xsl:text>
        <xsl:call-template name="print-occurs" >
-           <xsl:with-param name="name" select="@name" />
+           <xsl:with-param name="name" select="@name"/>
        </xsl:call-template>
-        <xsl:value-of select="$newline" />
+        <xsl:value-of select="$newline"/>
 -->
       </xsl:otherwise>
     </xsl:choose>
   </xsl:template>
 
   <xsl:template match="xs:complexType">
-    <xsl:param name="level" />
+    <xsl:param name="level"/>
-    <xsl:param name="name" />
+    <xsl:param name="name"/>
 
     <!-- Visit the sub-menus -->
     <xsl:apply-templates select="descendant::xs:element">
-      <xsl:with-param name="level" select="$level + 1" />
+      <xsl:with-param name="level" select="$level + 1"/>
-      <xsl:with-param name="prefix" select="concat($name, '.')" />
+      <xsl:with-param name="prefix" select="concat($name, '.')"/>
     </xsl:apply-templates>
   </xsl:template>
 
   <xsl:template match="xs:simpleType">
     <xsl:text>   - </xsl:text>
     <xsl:call-template name="print-annotation" >
-       <xsl:with-param name="indent" select="'     '" />
+       <xsl:with-param name="indent" select="'     '"/>
     </xsl:call-template>
   </xsl:template>
 
   <xsl:template name="print-occurs">
-    <xsl:param name="name" />
+    <xsl:param name="name"/>
   <!-- use the min/maxOccurs data to figure out if this is an optional
        item, and how many occurrences are allowed -->
     <xsl:variable name="min">
       <xsl:choose>
         <xsl:when test="@minOccurs">
-          <xsl:value-of select="@minOccurs" />
+          <xsl:value-of select="@minOccurs"/>
         </xsl:when>
         <xsl:otherwise>1</xsl:otherwise>
       </xsl:choose>
@@ -149,14 +152,14 @@
     <xsl:variable name="max">
       <xsl:choose>
         <xsl:when test="@maxOccurs">
-          <xsl:value-of select="@maxOccurs" />
+          <xsl:value-of select="@maxOccurs"/>
         </xsl:when>
         <xsl:otherwise>1</xsl:otherwise>
       </xsl:choose>
     </xsl:variable>
 
     <xsl:text>The **</xsl:text>
-    <xsl:value-of select="$name" />
+    <xsl:value-of select="$name"/>
     <xsl:text>** option is </xsl:text>
     <xsl:choose>
       <xsl:when test="$min = 0">
@@ -170,35 +173,57 @@
 
     <xsl:choose>
       <xsl:when test="($min = $max) or ($min = 0)">
-        <xsl:value-of select="$max" />
+        <xsl:value-of select="$max"/>
         <xsl:text> occurrence</xsl:text>
         <xsl:if test="$max &gt;  1">
           <xsl:text>s</xsl:text>
         </xsl:if>
       </xsl:when>
       <xsl:otherwise>
-        <xsl:value-of select="$min" />
+        <xsl:value-of select="$min"/>
         <xsl:text> to </xsl:text>
-        <xsl:value-of select="$max" />
+        <xsl:value-of select="$max"/>
         <xsl:text> occurrences</xsl:text>
       </xsl:otherwise>
     </xsl:choose>
     <xsl:text>.</xsl:text>
-    <xsl:value-of select="$newline" />
+    <xsl:value-of select="$newline"/>
   </xsl:template>
 
   <xsl:template name="print-annotation">
-    <xsl:param name="indent" />
+    <xsl:param name="indent"/>
+    <!-- append an (Optional) annotation if minOccurs=0) -->
+    <xsl:variable name="optional">
+      <xsl:choose>
+        <xsl:when test="@minOccurs">
+          <xsl:if test="@minOccurs = 0">
+             <xsl:text> *(Optional)*</xsl:text>
+          </xsl:if>
+        </xsl:when>
+        <!-- could show (Required) here instead, but it seemed too noisy -->
+        <xsl:otherwise><xsl:text></xsl:text></xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <!-- append a default value annotation if default was defined -->
+    <xsl:variable name="default">
+      <xsl:choose>
+        <xsl:when test="@default">
+          <xsl:value-of select="concat(' (Default value is ``', @default, '``)')"/>
+        </xsl:when>
+        <xsl:otherwise><xsl:text></xsl:text></xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+
     <xsl:choose>
       <xsl:when test="xs:annotation">
          <xsl:call-template name="printIndented">
-           <xsl:with-param name="text" select="xs:annotation/xs:documentation" />
+           <xsl:with-param name="text" select="concat(xs:annotation/xs:documentation, $optional, $default)"/>
-           <xsl:with-param name="indent" select="$indent" />
+           <xsl:with-param name="indent" select="$indent"/>
          </xsl:call-template>
       </xsl:when>
       <xsl:otherwise>
         <!-- <xsl:text>&lt;description is missing &gt;</xsl:text> -->
-        <xsl:value-of select="$newline" />
+        <xsl:value-of select="$newline"/>
       </xsl:otherwise>
     </xsl:choose>
   </xsl:template>
@@ -208,69 +233,70 @@
   -->
 
   <xsl:template name="repeat">
-    <xsl:param name="string" />
+    <xsl:param name="string"/>
-    <xsl:param name="times" />
+    <xsl:param name="times"/>
     <xsl:if test="$times > 0">
-      <xsl:value-of select="$string" />
+      <xsl:value-of select="$string"/>
       <xsl:call-template name="repeat">
-       <xsl:with-param name="string" select="$string" />
+       <xsl:with-param name="string" select="$string"/>
-       <xsl:with-param name="times" select="$times - 1" />
+       <xsl:with-param name="times" select="$times - 1"/>
       </xsl:call-template>
     </xsl:if>
   </xsl:template>
 
   <xsl:template name="section-header">
-    <xsl:param name="title" />
+    <xsl:param name="title"/>
-    <xsl:param name="label" />
+    <xsl:param name="label"/>
-    <xsl:param name="level" />
+    <xsl:param name="level"/>
     <xsl:if test="$label != ''">
-      <xsl:value-of select="concat('.. _', $label, ':', $newline, $newline)" />
+      <xsl:value-of select="concat($newline, '.. _', $label, ':', $newline, $newline)"/>
     </xsl:if>
-    <xsl:value-of select="concat($title, $newline)" />
+    <xsl:value-of select="concat($title, $newline)"/>
     <xsl:call-template name="repeat">
       <xsl:with-param name="string">
-       <xsl:value-of select="substring($section_adornment, $level, 1)" />
+       <xsl:value-of select="substring($section_adornment, $level, 1)"/>
       </xsl:with-param>
-      <xsl:with-param name="times" select="string-length($title)" />
+      <xsl:with-param name="times" select="string-length($title)"/>
     </xsl:call-template>
-    <xsl:value-of select="concat($newline, $newline)" />
+    <xsl:value-of select="concat($newline, $newline)"/>
   </xsl:template>
 
   <xsl:template name="option-header">
-    <xsl:param name="label" />
+    <xsl:param name="label"/>
     <!-- we're using the reST option directive for creating linkable
          config option sections using the :option: role.  This also
          gives us the option directive HTML formatting. -->
+    <xsl:value-of select="$newline"/>
     <xsl:text>.. option:: </xsl:text>
-    <xsl:value-of select="$label" />
+    <xsl:value-of select="$label"/>
-    <xsl:value-of select="$newline" />
+    <xsl:value-of select="$newline"/>
   </xsl:template>
 
 <xsl:template name="printIndented">
-  <xsl:param name="text" />
+  <xsl:param name="text"/>
-  <xsl:param name="indent" />
+  <xsl:param name="indent"/>
   <!-- Handle multi-line documentation text and indent it properly for
        the bullet list display we're using for node descriptions (but not for
        heading descriptions -->
   <xsl:if test="$text">
-    <xsl:variable name="thisLine" select="substring-before($text, $newline)" />
+    <xsl:variable name="thisLine" select="substring-before($text, $newline)"/>
-    <xsl:variable name="nextLine" select="substring-after($text, $newline)" />
+    <xsl:variable name="nextLine" select="substring-after($text, $newline)"/>
     <xsl:choose>
       <xsl:when test="$thisLine or $nextLine">
         <!-- $text contains at least one newline, and there's more coming so print it -->
-        <xsl:value-of select="concat($thisLine, $newline)" />
+        <xsl:value-of select="concat($thisLine, $newline)"/>
         <!-- watch for two newlines in a row and avoid writing the indent -->
         <xsl:if test="substring-before(concat($nextLine, $newline), $newline)" >
-          <xsl:value-of select="$indent" />
+          <xsl:value-of select="$indent"/>
         </xsl:if>
         <!-- and recurse to process the rest -->
         <xsl:call-template name="printIndented">
-          <xsl:with-param name="text" select="$nextLine" />
+          <xsl:with-param name="text" select="$nextLine"/>
-          <xsl:with-param name="indent" select="$indent" />
+          <xsl:with-param name="indent" select="$indent"/>
         </xsl:call-template>
       </xsl:when>
       <xsl:otherwise>
-        <xsl:value-of select="concat($text, $newline)" />
+        <xsl:value-of select="concat($text, $newline)"/>
       </xsl:otherwise>
     </xsl:choose>
   </xsl:if>

doc/tutorials/enable_ivshmem.rst

@@ -33,6 +33,8 @@ where
 
 .. note:: This device can be used with real-time VM (RTVM) as well.
 
+.. _ivshmem-hv:
+
 ivshmem hv-land usage
 *********************
 

misc/config_tools/schema/VMtypes.xsd

@@ -29,14 +29,14 @@
 <xs:simpleType name="GuestFlagsOptionsType">
   <xs:annotation>
     <xs:documentation>
-- 0, 0UL and empty string means there is no guest flag is enabled.
+- ``0``, ``0UL``, or an empty string means no guest flags are enabled.
-- ``GUEST_FLAG_SECURE_WORLD_ENABLED`` specify whether the secure world is
+- ``GUEST_FLAG_SECURE_WORLD_ENABLED`` specify that the secure world is
   enabled
-- ``GUEST_FLAG_LAPIC_PASSTHROUGH`` specify whether LAPIC is passed through
+- ``GUEST_FLAG_LAPIC_PASSTHROUGH`` specify that LAPIC is passed through
-- ``GUEST_FLAG_IO_COMPLETION_POLLING`` specify whether the hypervisor needs
+- ``GUEST_FLAG_IO_COMPLETION_POLLING`` specify that the hypervisor needs
   IO polling to completion
-- ``GUEST_FLAG_HIDE_MTRR`` specify whether to hide MTRR from the VM
+- ``GUEST_FLAG_HIDE_MTRR`` specify that MTRR is hidden from the VM
-- ``GUEST_FLAG_RT`` specify whether the VM is RT-VM (real-time)</xs:documentation>
+- ``GUEST_FLAG_RT`` specify that the VM is an RT-VM (real-time)</xs:documentation>
   </xs:annotation>
   <xs:restriction base="xs:string">
     <xs:enumeration value="" />
@@ -64,7 +64,8 @@
   <xs:sequence>
     <xs:element name="pcpu_id" type="xs:integer" default="2" 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>
@@ -76,7 +77,8 @@
       <xs:annotation>
         <xs:documentation>Configure each CPU in VMs to a desired CLOS ID in the ``VM`` section of the
 scenario file. Follow :ref:`rdt_detection_capabilities`
-to identify the maximum supported CLOS ID that can be used.</xs:documentation>
+to identify the maximum supported CLOS ID that can be used. Default
+value ``0``.</xs:documentation>
       </xs:annotation>
     </xs:element>
   </xs:sequence>
@@ -94,7 +96,8 @@ to identify the maximum supported CLOS ID that can be used.</xs:documentation>
     </xs:element>
     <xs:element name="size" type="HexFormat" default="0">
       <xs:annotation>
-        <xs:documentation>SGX EPC section size in Bytes, must be page aligned.</xs:documentation>
+        <xs:documentation>SGX EPC section size in Bytes, must be page
+aligned.</xs:documentation>
       </xs:annotation>
     </xs:element>
   </xs:sequence>
@@ -104,22 +107,26 @@ to identify the maximum supported CLOS ID that can be used.</xs:documentation>
   <xs:sequence>
     <xs:element name="start_hpa" type="HexFormat" default="0x100000000">
       <xs:annotation>
-        <xs:documentation>The start physical address in host for the VM.</xs:documentation>
+        <xs:documentation>The starting physical address in host for the
+VM.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="size" type="MemorySizeType" default="0x20000000">
       <xs:annotation>
-        <xs:documentation>The memory size in bytes for the VM.</xs:documentation>
+        <xs:documentation>The memory size in bytes for the VM. Default
+value is ``0x200000000``.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="start_hpa2" type="HexFormat" default="0x0" minOccurs="0">
       <xs:annotation acrn:configurable="n">
-        <xs:documentation>Start of second HPA for non-contiguous allocations in host for the VM.</xs:documentation>
+        <xs:documentation>Start of second HPA for non-contiguous
+allocations in host for the VM.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="size_hpa2" type="MemorySizeType" default="0x0" minOccurs="0">
       <xs:annotation acrn:configurable="n">
-        <xs:documentation>Memory size of second HPA for non-contiguous allocations in Bytes for the VM.</xs:documentation>
+        <xs:documentation>Memory size of second HPA for non-contiguous
+allocations in Bytes for the VM.</xs:documentation>
       </xs:annotation>
     </xs:element>
   </xs:sequence>
@@ -128,10 +135,13 @@ to identify the maximum supported CLOS ID that can be used.</xs:documentation>
 <xs:complexType name="OSConfigurations">
   <xs:sequence>
     <xs:element name="name">
-      <xs:simpleType>
         <xs:annotation>
-          <xs:documentation>Specify the OS name of VM; currently, it is not referenced by the hypervisor code.String from 1 to 32
+          <xs:documentation>Specify the OS name of VM.
-characters long.</xs:documentation>
+Is not referenced by the hypervisor code. </xs:documentation>
+        </xs:annotation>
+        <xs:simpleType>
+        <xs:annotation>
+          <xs:documentation>A string with 1 to 32 characters.</xs:documentation>
         </xs:annotation>
         <xs:restriction base="xs:string">
           <xs:minLength value="1" />
@@ -141,8 +151,7 @@ characters long.</xs:documentation>
     </xs:element>
     <xs:element name="kern_type" type="VMKernelType">
       <xs:annotation>
-        <xs:documentation>Specify the kernel image type so that the hypervisor can load it correctly.
+        <xs:documentation>Specify the kernel image type so the hypervisor can load it correctly.</xs:documentation>
-Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="kern_mod" type="xs:string">
@@ -177,8 +186,8 @@ must exactly match the module tag in the GRUB multiboot cmdline.</xs:documentati
 
 <xs:simpleType name="VMKernelType">
   <xs:annotation>
-    <xs:documentation>Specify the kernel image type so that the hypervisor can load it correctly.
+    <xs:documentation>A string with either ``KERNEL_BZIMAGE`` or
-Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.</xs:documentation>
+``KERNEL_ZEPHYR``.</xs:documentation>
   </xs:annotation>
   <xs:restriction base="xs:string">
     <xs:enumeration value="KERNEL_BZIMAGE" />
@@ -198,7 +207,9 @@ Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.</xs:documentation>
 
 <xs:simpleType name="LegacyVuartBase">
   <xs:annotation>
-    <xs:documentation>vUART (A.K.A COM) enabling switch. Enable by exposing its base address, disable by returning INVALID_COM_BASE.</xs:documentation>
+    <xs:documentation>A string with either ``SOS_COM1_BASE``,
+``SOS_COM2_BASE``, ``COM1_BASE``, ``COM2_BASE``, ``COM3_BASE``,
+``COM4_BASE``, or indicating it's disabled with ``INVALID_COM_BASE``.</xs:documentation>
   </xs:annotation>
   <xs:restriction base="xs:string">
     <xs:enumeration value="SOS_COM1_BASE" />
@@ -213,7 +224,9 @@ Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.</xs:documentation>
 
 <xs:simpleType name="LegacyVuartIrq">
   <xs:annotation acrn:configurable="n">
-    <xs:documentation>vCOM irq</xs:documentation>
+    <xs:documentation>A string with either ``SOS_COM1_IRQ``,
+``SOS_COM2_IRQ``, ``COM1_IRQ``, ``COM2_IRQ``, ``COM3_IRQ``,
+``COM4_IRQ``, ``CONFIG_COM_IRQ``, ``3``, ``4``, ``6``, or ``7``.</xs:documentation>
   </xs:annotation>
   <xs:restriction base="xs:string">
     <xs:enumeration value="SOS_COM1_IRQ" />
@@ -230,17 +243,19 @@ Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.</xs:documentation>
   </xs:restriction>
 </xs:simpleType>
 
-<xs:complexType name="LegancyVuartConfiguration">
+<xs:complexType name="LegacyVuartConfiguration">
   <xs:sequence>
     <xs:element name="type" type="LegacyVuartType" default="VUART_LEGACY_PIO">
       <xs:annotation>
-        <xs:documentation>vUART (aka COM) type; currently only supports the legacy PIO mode.</xs:documentation>
+        <xs:documentation>vUART (COM) type; only legacy PIO mode is
+supported.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="base" type="LegacyVuartBase">
       <xs:annotation>
-        <xs:documentation>vUART (A.K.A COM) enabling switch. Enable by exposing its COM_BASE
+        <xs:documentation>vUART (COM) enabling switch. Enable by exposing its COM_BASE
-(SOS_COM_BASE for Service VM); disable by returning INVALID_COM_BASE.</xs:documentation>
+(e.b., ``SOS_COM1_BASE`` for Service VM); disable by returning
+``INVALID_COM_BASE``.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="irq" type="LegacyVuartIrq">
@@ -265,8 +280,8 @@ target VM the current VM connects to.</xs:documentation>
 
 <xs:simpleType name="PCIVuartBase">
   <xs:annotation>
-    <xs:documentation>PCI based vUART enabling switch. Enable by specifying PCI_VUART;
+    <xs:documentation>A string with ``PCI_VUART`` or indicating its
-disable by returning INVALID_PCI_BASE.</xs:documentation>
+disabled using ``INVALID_PCI_BASE``.</xs:documentation>
   </xs:annotation>
   <xs:restriction base="xs:string">
     <xs:enumeration value="PCI_VUART" />
@@ -279,7 +294,8 @@ disable by returning INVALID_PCI_BASE.</xs:documentation>
     <xs:element name="base" type="PCIVuartBase" default="INVALID_PCI_BASE">
       <xs:annotation>
         <xs:documentation>Console vUART (A.K.A PCI based vUART) enabling switch.
-  Enable by specifying PCI_VUART; disable by returning INVALID_PCI_BASE.</xs:documentation>
+Enable by specifying PCI_VUART; disable by specifying
+``INVALID_PCI_BASE``.</xs:documentation>
       </xs:annotation>
     </xs:element>
   </xs:sequence>
@@ -291,7 +307,8 @@ disable by returning INVALID_PCI_BASE.</xs:documentation>
     <xs:element name="base" type="PCIVuartBase" default="INVALID_PCI_BASE">
       <xs:annotation>
         <xs:documentation>Communication vUART (A.K.A PCI based vUART) enabling switch.
-Enable by specifying PCI_VUART; disable by returning INVALID_PCI_BASE.</xs:documentation>
+Enable by specifying PCI_VUART; disable by specifying
+``INVALID_PCI_BASE``.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="target_vm_id" type="xs:integer">
@@ -312,12 +329,13 @@ Enable by specifying PCI_VUART; disable by returning INVALID_PCI_BASE.</xs:docum
   <xs:sequence>
     <xs:element name="TPM2" type="Boolean" default="n" minOccurs="0">
       <xs:annotation>
-        <xs:documentation>TPM2 device to passthrough.</xs:documentation>
+        <xs:documentation>Specify TPM2 device to passthrough.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="p2sb" type="Boolean" default="n" minOccurs="0">
       <xs:annotation>
-        <xs:documentation>Exposing the P2SB (Primary-to-Sideband) bridge to the pre-launched VM.</xs:documentation>
+        <xs:documentation>Expose the P2SB (Primary-to-Sideband) bridge
+to the pre-launched VM.</xs:documentation>
       </xs:annotation>
     </xs:element>
   </xs:sequence>

misc/config_tools/schema/config.xsd

@@ -16,54 +16,55 @@
     <xs:element name="RELEASE" type="Boolean" default="n">
       <xs:annotation>
         <xs:documentation>Build an image for release (``y``) or debug (``n``).
-In a **release** image, assertions are not enforced and these features
+In a **release** image, assertions are not enforced and debugging
-are **not** available:
+features are disabled, including logs, serial console, and the
-
+hypervisor shell.</xs:documentation>
-- logs
-- serial console
-- hypervisor shell</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="SERIAL_CONSOLE" type="SerialConsoleOptions" default="/dev/ttyS0">
       <xs:annotation>
         <xs:documentation>Specify the host serial device used for hypervisor debugging.
-This option is only valid if the Service VM 'legacy_vuart` is
+This option is only valid if the Service VM :ref:`vm.legacy_vuart` is
-enabled. Leave this filed empty if the Service VM's 'console_vuart` is enabled. Uses
+enabled. Leave this field empty if the Service VM's :ref:`vm.console_vuart` is enabled. Uses
-`bootargs` for `console_vuart` configuration.</xs:documentation>
+:option:`vm.os_config.bootargs` for :ref:`vm.console_vuart`
+configuration.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="MEM_LOGLEVEL" type="LogLevelType" default="5">
       <xs:annotation>
-        <xs:documentation>Default loglevel for log messages stored in memory.
+        <xs:documentation>Default loglevel for log messages stored in
-Messages with a lower severity (higher value) are discarded.</xs:documentation>
+memory. Value can be changed at runtime.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="NPK_LOGLEVEL" type="LogLevelType" default="5">
       <xs:annotation>
-        <xs:documentation>Default loglevel for the hypervisor NPK log.</xs:documentation>
+        <xs:documentation>Default loglevel for the hypervisor North Peak
+(NPK) log. Value can be changed at runtime.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="CONSOLE_LOGLEVEL" type="LogLevelType" default="3">
       <xs:annotation>
         <xs:documentation>Default loglevel for log messages
-written to the serial console. Messages with lower severity (higher
+written to the serial console.</xs:documentation>
-value) are not displayed.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="LOG_DESTINATION" default="7">
-    <xs:simpleType>
       <xs:annotation>
         <xs:documentation>Bitmap indicating the destination of log messages.
-Currently there are three log destinations available:
+There are three log destinations available:
 
-- bit 0 for the serial console (``0x1``),
+- bit 0 enables the serial console (``0x1``),
-- bit 1 for the Service VM log (``0x2``), and
+- bit 1 enables the Service VM log (``0x2``), and
-- bit 2 for the NPK log (``0x4``).
+- bit 2 enables the NPK log (``0x4``).
 
 For example, a value of ``3`` enables only the
 serial console and Service VM logs. Effective only in debug builds (when
 :option:`hv.DEBUG_OPTIONS.RELEASE` is ``n``).</xs:documentation>
       </xs:annotation>
+    <xs:simpleType>
+      <xs:annotation>
+        <xs:documentation>integer value from 0 to 7.</xs:documentation>
+      </xs:annotation>
       <xs:restriction base="xs:integer">
         <xs:minInclusive value="0" />
         <xs:maxInclusive value="7" />
@@ -81,13 +82,14 @@ physical cpu, for example, ``0x40000``.</xs:documentation>
 
 <xs:complexType name="FeatureOptionsType">
   <xs:annotation>
-    <xs:documentation>Options for hypervisor feature enablement.</xs:documentation>
+    <xs:documentation>Options for enabling hypervisor features.</xs:documentation>
   </xs:annotation>
 
   <xs:all>
     <xs:element name="RELOC" type="Boolean" default="y">
       <xs:annotation>
-        <xs:documentation>Specify if hypervisor relocation is enabled on booting.</xs:documentation>
+        <xs:documentation>Specify if hypervisor relocation is enabled on
+booting.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="SCHEDULER" type="SchedulerType" default="SCHED_BVT">
@@ -127,7 +129,8 @@ of DMA operations.</xs:documentation>
     </xs:element>
     <xs:element name="L1D_VMENTRY_ENABLED" type="Boolean" default="n">
       <xs:annotation>
-        <xs:documentation>Enable L1 cache flush before VM entry.</xs:documentation>
+        <xs:documentation>Enable L1 cache flush before VM entry. Default
+value ``n``.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="MCE_ON_PSC_DISABLED" type="Boolean" default="n">
@@ -172,22 +175,25 @@ the RAM region used by the hypervisor.</xs:documentation>
     <xs:element name="LOW_RAM_SIZE" type="HexFormat" default="0x00010000">
       <xs:annotation>
         <xs:documentation>Size of the low RAM region below address
-``0x10000``, starting from address ``0x0``..</xs:documentation>
+``0x10000``, starting from address ``0x0``.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="UOS_RAM_SIZE" type="HexFormat" default="0x200000000">
       <xs:annotation>
-        <xs:documentation>Size of the User VM OS RAM region.</xs:documentation>
+        <xs:documentation>Size of the User VM OS RAM region. Default
+value ``0x200000000``.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="SOS_RAM_SIZE" type="HexFormat" default="0x400000000">
       <xs:annotation>
-        <xs:documentation>Size of the Service VM OS RAM region.</xs:documentation>
+        <xs:documentation>Size of the Service VM OS RAM region. Default
+value ``0x400000000``.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="PLATFORM_RAM_SIZE" type="HexFormat" default="0x400000000">
       <xs:annotation>
-        <xs:documentation>Size of the physical platform RAM.</xs:documentation>
+        <xs:documentation>Size of the physical platform RAM. Default
+value ``0x400000000``.</xs:documentation>
       </xs:annotation>
     </xs:element>
   </xs:all>
@@ -201,7 +207,8 @@ maximum supported resource.</xs:documentation>
   <xs:all>
     <xs:element name="IOMMU_BUS_NUM" type="HexFormat" default="0x100">
       <xs:annotation>
-        <xs:documentation>Highest PCI bus ID used during IOMMU initialization.</xs:documentation>
+        <xs:documentation>Highest PCI bus ID used during IOMMU
+initialization.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="MAX_IR_ENTRIES" type="xs:integer" default="256">
@@ -210,10 +217,13 @@ maximum supported resource.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="MAX_IOAPIC_NUM" default="1">
+      <xs:annotation>
+        <xs:documentation>Maximum number of IOAPICs.</xs:documentation>
+      </xs:annotation>
       <xs:simpleType>
-        <xs:annotation>
+         <xs:annotation>
-          <xs:documentation>Maximum number of IO-APICs. Integer from 1 to 10.</xs:documentation>
+           <xs:documentation>integer from 1 to 10.</xs:documentation>
-        </xs:annotation>
+         </xs:annotation>
         <xs:restriction base="xs:integer">
           <xs:minInclusive value="1" />
           <xs:maxInclusive value="10" />
@@ -222,14 +232,17 @@ maximum supported resource.</xs:documentation>
     </xs:element>
     <xs:element name="MAX_KATA_VM_NUM" type="xs:integer" minOccurs="0" default="0">
       <xs:annotation>
-        <xs:documentation>>Maximum number of KATA VM.</xs:documentation>
+        <xs:documentation>Maximum number of KATA VM.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="MAX_PCI_DEV_NUM" default="96">
+      <xs:annotation>
+        <xs:documentation>Maximum number of PCI devices.</xs:documentation>
+      </xs:annotation>
       <xs:simpleType>
-        <xs:annotation>
+         <xs:annotation>
-          <xs:documentation>Maximum number of PCI devices.Integer from 1 to 1024.</xs:documentation>
+           <xs:documentation>integer from 1 to 1024.</xs:documentation>
-        </xs:annotation>
+         </xs:annotation>
         <xs:restriction base="xs:integer">
           <xs:minInclusive value="1" />
           <xs:maxInclusive value="1024" />
@@ -237,10 +250,13 @@ maximum supported resource.</xs:documentation>
       </xs:simpleType>
     </xs:element>
     <xs:element name="MAX_IOAPIC_LINES" default="120">
+      <xs:annotation>
+        <xs:documentation>Maximum number of interrupt lines per IOAPIC.</xs:documentation>
+      </xs:annotation>
       <xs:simpleType>
-        <xs:annotation>
+         <xs:annotation>
-          <xs:documentation>Maximum number of interrupt lines per IOAPIC.Integer from 1 to 120.</xs:documentation>
+           <xs:documentation>integer from 1 to 120.</xs:documentation>
-        </xs:annotation>
+         </xs:annotation>
         <xs:restriction base="xs:integer">
           <xs:minInclusive value="1" />
           <xs:maxInclusive value="120" />
@@ -249,14 +265,17 @@ maximum supported resource.</xs:documentation>
     </xs:element>
     <xs:element name="MAX_PT_IRQ_ENTRIES" type="xs:integer" default="256">
       <xs:annotation>
-        <xs:documentation>Maximum number of interrupt source for PT devices.</xs:documentation>
+        <xs:documentation>Maximum number of interrupt source for PT
+devices.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="MAX_MSIX_TABLE_NUM" default="64">
+        <xs:annotation>
+          <xs:documentation>Maximum number of MSI-X tables per device.</xs:documentation>
+        </xs:annotation>
       <xs:simpleType>
         <xs:annotation>
-          <xs:documentation>Maximum number of MSI-X tables per device.
+          <xs:documentation>integer value from 1 to 2048.</xs:documentation>
-Leave blank if not sure.Integer from 1 to 2048.</xs:documentation>
         </xs:annotation>
         <xs:restriction base="xs:integer">
           <xs:minInclusive value="1" />
@@ -265,9 +284,12 @@ Leave blank if not sure.Integer from 1 to 2048.</xs:documentation>
       </xs:simpleType>
     </xs:element>
     <xs:element name="MAX_EMULATED_MMIO" default="16">
+        <xs:annotation>
+          <xs:documentation>Maximum number of emulated MMIO regions.</xs:documentation>
+        </xs:annotation>
       <xs:simpleType>
         <xs:annotation>
-          <xs:documentation>Maximum number of emulated MMIO regions.Integer from 1 to 128.</xs:documentation>
+          <xs:documentation>integer value from 1 to 128.</xs:documentation>
         </xs:annotation>
         <xs:restriction base="xs:integer">
           <xs:minInclusive value="1" />
@@ -311,11 +333,13 @@ Leave blank if not sure.Integer from 1 to 2048.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="name" minOccurs="0">
-      <xs:simpleType>
         <xs:annotation>
           <xs:documentation>Specify the VM name shown in the
-  hypervisor console ``vm_lists`` command. String from 1 to 32
+hypervisor console ``vm_lists`` command.</xs:documentation>
-  characters long.</xs:documentation>
+        </xs:annotation>
+      <xs:simpleType>
+        <xs:annotation>
+          <xs:documentation>string from 1 to 32 characters long.</xs:documentation>
         </xs:annotation>
         <xs:restriction base="xs:string">
           <xs:minLength value="1" />
@@ -346,35 +370,16 @@ Refer SDM 17.19.2 for details, and use with caution.</xs:documentation>
     </xs:element>
     <xs:element name="memory" type="MemoryInfo" minOccurs="0">
       <xs:annotation>
-        <xs:documentation>Specify memory information for hypervisor, Service OS and User OS:
+        <xs:documentation>Specify memory information for Service and User VMs.</xs:documentation>
-
-- ``STACK_SIZE``: Capacity of one stack, in bytes.
-- ``HV_RAM_SIZE``: Size of the RAM region used by the hypervisor.
-- ``HV_RAM_STAR``: 2M-aligned Start physical address of the RAM region used by the hypervisor.
-- ``LOW_RAM_SIZE``: Size of the low RAM region.
-- ``SOS_RAM_SIZE``: Size of the Service OS (SOS) RAM.
-- ``PLATFORM_RAM_SIZE``: Size of the physical platform RAM.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="os_config" type="OSConfigurations" minOccurs="0">
       <xs:annotation>
-        <xs:documentation>General information for host kernel, boot argument and memory,
+        <xs:documentation>General information for host kernel, boot
-the following elements are configured in this section:
+argument and memory.</xs:documentation>
-
-- ``name``: Specify the OS name of VM; currently, it is not referenced by the hypervisor code.
-- ``kern_type``: Specify the kernel image type so that the hypervisor can load it correctly.
-  Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.
-- ``kern_mod``: The tag for the kernel image that acts as a multiboot module; it must
-  exactly match the module tag in the GRUB multiboot cmdline.
-- ``ramdisk_mod``: The tag for the ramdisk image, which acts as a multiboot module; it
-  must exactly match the module tag in the GRUB multiboot cmdline.
-- ``bootargs``: For internal use only and is not configurable. Specify the kernel boot arguments
-  in ``bootargs`` under the parent of ``board_private``.
-- ``kern_load_addr``: The loading address in host memory for the VM kernel.
-- ``kern_entry_addr``: The entry address in host memory for the VM kernel.</xs:documentation>
       </xs:annotation>
     </xs:element>
-    <xs:element name="legacy_vuart" type="LegancyVuartConfiguration" minOccurs="2" maxOccurs="2">
+    <xs:element name="legacy_vuart" type="LegacyVuartConfiguration" minOccurs="2" maxOccurs="2">
       <xs:annotation>
         <xs:documentation>Specify the vUART (aka COM) with the vUART ID by its ``id`` attribute.
 Refer to :ref:`vuart_config` for detailed vUART settings.</xs:documentation>
@@ -389,7 +394,7 @@ its ``id`` attribute.</xs:documentation>
     <xs:element name="communication_vuart" type="CommunicationVuartConfiguration" maxOccurs="unbounded">
       <xs:annotation>
         <xs:documentation>Specify the communication vUART (aka PCI based vUART) with the vUART ID by
-its ``id`` attribute. When it is enabled, specify which target VM's vuart the current VM connects to.</xs:documentation>
+its ``id`` attribute. When it is enabled, specify which target VM's vUART the current VM connects to.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="mmio_resources" type="MMIOResourcesConfiguration" minOccurs="0">
@@ -409,7 +414,7 @@ its ``id`` attribute. When it is enabled, specify which target VM's vuart the cu
     </xs:element>
     <xs:element name="pci_devs" type="PCIDevsConfiguration" minOccurs="0">
       <xs:annotation>
-        <xs:documentation>pci devices list.</xs:documentation>
+        <xs:documentation>PCI devices list.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="board_private" type="BoardPrivateConfiguration" minOccurs="0" />

misc/config_tools/schema/types.xsd

@@ -28,21 +28,21 @@
 
 <xs:simpleType name="HVRamSizeType">
   <xs:annotation>
-    <xs:documentation>Either empty, or a hexadecimal value.</xs:documentation>
+    <xs:documentation>Either empty, or an integer value in hexadecimal format.</xs:documentation>
   </xs:annotation>
   <xs:union memberTypes="None HexFormat" />
 </xs:simpleType>
 
 <xs:simpleType name="HVRamStartType">
   <xs:annotation>
-    <xs:documentation>Either empty, or a hexadecimal value.</xs:documentation>
+    <xs:documentation>Either empty, or an integer value in hexadecimal format.</xs:documentation>
   </xs:annotation>
   <xs:union memberTypes="None HexFormat" />
 </xs:simpleType>
 
 <xs:simpleType name="MaxMsixTableNumType">
   <xs:annotation>
-    <xs:documentation>Integer from 1 to 2048.</xs:documentation>
+    <xs:documentation>integer from 1 to 2048.</xs:documentation>
   </xs:annotation>
   <xs:restriction base="xs:integer">
     <xs:minInclusive value="1" />
@@ -65,8 +65,7 @@
 
 <xs:simpleType name="MemorySizeType">
   <xs:annotation>
-    <xs:documentation>Either a hexadecimal value or the string
+    <xs:documentation>An integer value in hexadecimal format.</xs:documentation>
-``CONFIG_SOS_RAM_SIZE``.</xs:documentation>
   </xs:annotation>
   <xs:union memberTypes="SOSRamSize HexFormat" />
 </xs:simpleType>
@@ -83,9 +82,8 @@ severity and intent:
 - 5 (LOG_INFO) informational
 - 6 (LOG_DEBUG) debug-level messages
 
-Note that lower values have a higher severity. Only log messages with a
+A lower value has a higher severity. Log messages with a
-severity level higher (lower value) than a specified value will be
+higher value (lower severity) are discarded.</xs:documentation>
-recorded.</xs:documentation>
   </xs:annotation>
   <xs:restriction base="xs:integer">
     <xs:minInclusive value="0" />
@@ -125,7 +123,7 @@ Read more about the available scheduling options in :ref:`cpu_sharing`.</xs:docu
 
 <xs:simpleType name="SerialConsoleOptions">
   <xs:annotation>
-    <xs:documentation>Either empty or a string.</xs:documentation>
+    <xs:documentation>Either empty or a string, such as ``/dev/ttyS0``.</xs:documentation>
   </xs:annotation>
   <xs:union memberTypes="None SerialConsoleType" />
 </xs:simpleType>
@@ -138,7 +136,9 @@ Read more about the available scheduling options in :ref:`cpu_sharing`.</xs:docu
 
 <xs:simpleType name="IVSHMEMRegionType">
   <xs:annotation>
-    <xs:documentation>Either empty or a string.</xs:documentation>
+    <xs:documentation>Either empty or a string naming the shared region,
+its size, and the VM IDs that can access it, such as ``hv:/shm_region_0, 2, 0:2``.
+See :ref:`ivshmem-hv` for more information.</xs:documentation>
   </xs:annotation>
   <xs:union memberTypes="None IVSHMEMRegionPattern" />
 
@@ -148,7 +148,8 @@ Read more about the available scheduling options in :ref:`cpu_sharing`.</xs:docu
   <xs:sequence>
    <xs:element name="IVSHMEM_ENABLED" type="Boolean" default="n">
      <xs:annotation>
-       <xs:documentation>Enable inter-VM shared memory (IVSHMEM) feature.</xs:documentation>
+       <xs:documentation>Enable inter-VM shared memory (IVSHMEM)
+feature.</xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="IVSHMEM_REGION" type="IVSHMEMRegionType">
@@ -181,7 +182,8 @@ RDT, setting this option to ``y`` is ignored.</xs:documentation>
       <xs:annotation>
         <xs:documentation>Specify whether to enable Code and Data Prioritization (CDP).
 CDP is an extension of CAT. Set to 'y' to enable the feature or 'n' to disable it.
-The 'y' will be ignored when hardware does not support CDP.</xs:documentation>
+The 'y' will be ignored when hardware does not support CDP. Default
+value ``n``.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="CLOS_MASK" type="xs:string"  minOccurs="0" maxOccurs="unbounded">
@@ -202,7 +204,8 @@ are allowed. The value will be ignored when hardware does not support RDT.</xs:d
   <xs:sequence>
     <xs:element name="PSRAM_ENABLED" type="Boolean" default="n">
       <xs:annotation>
-        <xs:documentation>Enable PTCM (Platform Tuning Configuration Manager).</xs:documentation>
+        <xs:documentation>Enable PTCM (Platform Tuning Configuration
+Manager).</xs:documentation>
       </xs:annotation>
     </xs:element>
   </xs:sequence>