OrgACRN
/
acrn-hypervisor
mirror of https://github.com/projectacrn/acrn-hypervisor.git
1
0
Fork 0
Code Issues Releases Wiki Activity

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>
This commit is contained in:
David B. Kinder 2021-02-02 17:28:21 -08:00 committed by David Kinder
parent c741468b9c
commit 07f4b9f5eb
6 changed files with 244 additions and 188 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/reference/config-options.rst
View File

@ -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

174
doc/scripts/configdoc.xsl
View File

@ -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="section_adornment" select="'#*=-%+@`'" />
<xsl:variable name="newline" select="'&#xa;'"/>
<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="prefix" select="''" />
<xsl:with-param name="level" select="2"/>
<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="prefix" />
<xsl:param name="level"/>
<xsl:param name="prefix"/>
<xsl:apply-templates select="descendant::xs:element">
<xsl:with-param name="level" select="$level" />
<xsl:with-param name="prefix" select="$prefix" />
<xsl:with-param name="level" select="$level"/>
<xsl:with-param name="prefix" select="$prefix"/>
</xsl:apply-templates>
</xsl:template>
<xsl:template match="xs:element">
<xsl:param name="level" />
<xsl:param name="prefix" />
<xsl:param name="level"/>
<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="label" select="concat($prefix, @name)" />
<xsl:with-param name="level" select="$level" />
<xsl:with-param name="title" select="concat($prefix, @name)"/>
<xsl:with-param name="label" select="concat($prefix, @name)"/>
<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="name" select="concat($prefix, @name)" />
<xsl:with-param name="level" select="$level"/>
<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="$newline" />
<xsl:value-of select="substring($ty, 4)"/>
<xsl:value-of select="$newline"/>
</xsl:when>
<xsl:otherwise>
<xsl:text> - </xsl:text>
<xsl:value-of select="$ty" />
<xsl:value-of select="$newline" />
<!-- element doesn't have a named type, check for an unnamed simpleType child -->
<xsl:apply-templates select="descendant::xs:simpleType">
<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="name" />
<xsl:param name="level"/>
<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="prefix" select="concat($name, '.')" />
<xsl:with-param name="level" select="$level + 1"/>
<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="indent" select="$indent" />
<xsl:with-param name="text" select="concat(xs:annotation/xs:documentation, $optional, $default)"/>
<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="times" />
<xsl:param name="string"/>
<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="times" select="$times - 1" />
<xsl:with-param name="string" select="$string"/>
<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="label" />
<xsl:param name="level" />
<xsl:param name="title"/>
<xsl:param name="label"/>
<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="$newline" />
<xsl:value-of select="$label"/>
<xsl:value-of select="$newline"/>
</xsl:template>
<xsl:template name="printIndented">
<xsl:param name="text" />
<xsl:param name="indent" />
<xsl:param name="text"/>
<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="nextLine" select="substring-after($text, $newline)" />
<xsl:variable name="thisLine" select="substring-before($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="indent" select="$indent" />
<xsl:with-param name="text" select="$nextLine"/>
<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>

2
doc/tutorials/enable_ivshmem.rst
View File

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

82
misc/config_tools/schema/VMtypes.xsd
View File

@ -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.
- ``GUEST_FLAG_SECURE_WORLD_ENABLED`` specify whether the secure world is
- ``0``, ``0UL``, or an empty string means no guest flags are enabled.
- ``GUEST_FLAG_SECURE_WORLD_ENABLED`` specify that the secure world is
enabled
- ``GUEST_FLAG_LAPIC_PASSTHROUGH`` specify whether LAPIC is passed through
- ``GUEST_FLAG_IO_COMPLETION_POLLING`` specify whether the hypervisor needs
- ``GUEST_FLAG_LAPIC_PASSTHROUGH`` specify that LAPIC is passed through
- ``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_RT`` specify whether the VM is RT-VM (real-time)</xs:documentation>
- ``GUEST_FLAG_HIDE_MTRR`` specify that MTRR is hidden from the VM
- ``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
characters long.</xs:documentation>
<xs:documentation>Specify the OS name of VM.
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.
Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.</xs:documentation>
<xs:documentation>Specify the kernel image type so the hypervisor can load it correctly.</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.
Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.</xs:documentation>
<xs:documentation>A string with either ``KERNEL_BZIMAGE`` or
``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
(SOS_COM_BASE for Service VM); disable by returning INVALID_COM_BASE.</xs:documentation>
<xs:documentation>vUART (COM) enabling switch. Enable by exposing its COM_BASE
(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;
disable by returning INVALID_PCI_BASE.</xs:documentation>
<xs:documentation>A string with ``PCI_VUART`` or indicating its
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>

143
misc/config_tools/schema/config.xsd
View File

@ -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
are **not** available:
- logs
- serial console
- hypervisor shell</xs:documentation>
In a **release** image, assertions are not enforced and debugging
features are disabled, including logs, serial console, and the
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
enabled. Leave this filed empty if the Service VM's 'console_vuart` is enabled. Uses
`bootargs` for `console_vuart` configuration.</xs:documentation>
This option is only valid if the Service VM :ref:`vm.legacy_vuart` is
enabled. Leave this field empty if the Service VM's :ref:`vm.console_vuart` is enabled. Uses
: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.
Messages with a lower severity (higher value) are discarded.</xs:documentation>
<xs:documentation>Default loglevel for log messages stored in
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
value) are not displayed.</xs:documentation>
written to the serial console.</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 1 for the Service VM log (``0x2``), and
- bit 2 for the NPK log (``0x4``).
- bit 0 enables the serial console (``0x1``),
- bit 1 enables the Service VM log (``0x2``), and
- 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:documentation>Maximum number of IO-APICs. Integer from 1 to 10.</xs:documentation>
</xs:annotation>
<xs:annotation>
<xs:documentation>integer from 1 to 10.</xs:documentation>
</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:documentation>Maximum number of PCI devices.Integer from 1 to 1024.</xs:documentation>
</xs:annotation>
<xs:annotation>
<xs:documentation>integer from 1 to 1024.</xs:documentation>
</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:documentation>Maximum number of interrupt lines per IOAPIC.Integer from 1 to 120.</xs:documentation>
</xs:annotation>
<xs:annotation>
<xs:documentation>integer from 1 to 120.</xs:documentation>
</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.
Leave blank if not sure.Integer from 1 to 2048.</xs:documentation>
<xs:documentation>integer value 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
characters long.</xs:documentation>
hypervisor console ``vm_lists`` command.</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:
- ``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:documentation>Specify memory information for Service and User VMs.</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,
the following elements are configured in this section:
- ``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:documentation>General information for host kernel, boot
argument and memory.</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" />

29
misc/config_tools/schema/types.xsd
View File

@ -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
``CONFIG_SOS_RAM_SIZE``.</xs:documentation>
<xs:documentation>An integer value in hexadecimal format.</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
severity level higher (lower value) than a specified value will be
recorded.</xs:documentation>
A lower value has a higher severity. Log messages with a
higher value (lower severity) are discarded.</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>