github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-23 05:57:33 +00:00
Code Issues Projects Releases Wiki Activity

doc: use DX-friendly names in configuration option documentation

Browse Source 
Change the generated config option documentation to use the DX-friendly
names defined for the configurator UI (instead of the XML element name
hierarchy previously used).

Options are grouped by the top-level section (aka complex type) they
belong to and then sorted alphabetically with these groups.

Use badges to indicate where options can be found in the configurator UI
and whether they're applicable to the Hypervisor or Pre/Post/Service VM.
Add a custom css style for the config-option doc that puts the first
paragraph of a glossary item on the same line as the glossary term so
these badges look pretty.

Added a acrn-custom.js patch that copies the alt text for images into a
title property for images within the config-doc document.  This provides
tooltip text when hovering over the badges.

Don't display options not visible in the configurator UI (elements with
acrn:views="").

A missing acrn:views or acrn:applicable-vm means we look for an
applicable value from an ancestor element.

Add processing of a second xs:documentation element within an
xs:annotation element. This second documentation element's content will
be appended as a new paragraph to the first xs:documentation content in
the generated documentation. Only the first xs:documentation element is
used by the Configurator for its tooltips.

Update documents that were referring to options by their XML names.

Because we're now using a glossary to provide links to config options,
we can't duplicate option names or glosary names anywhere in the doc
set.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2022-04-20 14:09:22 -07:00 committed by David Kinder
parent f8f1689a88
commit f71c7a8032
16 changed files with 328 additions and 188 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/developer-guides/doc_guidelines.rst
View File

@ -751,9 +751,9 @@ During the documentation ``make html`` processing, the documentation annotations
in the ``.xsd`` files are extracted and transformed into reStructuredText using in the ``.xsd`` files are extracted and transformed into reStructuredText using
an XSLT transformation found in ``doc/scripts/configdoc.xsl``. The generated an XSLT transformation found in ``doc/scripts/configdoc.xsl``. The generated
option documentation is organized and formatted to make it easy to create links option documentation is organized and formatted to make it easy to create links
to specific option descriptions using an ``:option:`` role, for example, to specific option descriptions using an ``:term:`` role, for example,
``:option:`hv.DEBUG_OPTIONS.BUILD_TYPE``` would link to ``:term::`Build type``` would link to
:option:`hv.DEBUG_OPTIONS.BUILD_TYPE`. :term:`Build type`.
The transformed option documentation is The transformed option documentation is
created in the ``_build/rst/reference/configdoc.txt`` file and included by created in the ``_build/rst/reference/configdoc.txt`` file and included by

1
doc/glossary.rst
View File

@ -177,7 +177,6 @@ Glossary of Terms
post-launched standard, and post-launched real-time. *(Historically, a post-launched standard, and post-launched real-time. *(Historically, a
User VM was also called a User OS, or simply UOS.)* User VM was also called a User OS, or simply UOS.)*
VM
Virtual Machine Virtual Machine
A compute resource that uses software instead of physical hardware to run a A compute resource that uses software instead of physical hardware to run a
program. Multiple VMs can run independently on the same physical machine, program. Multiple VMs can run independently on the same physical machine,

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

@ -20,8 +20,7 @@ Within this option documentation, we refer to some common type
definitions: definitions:
Boolean Boolean
A true or false value specified as either ``y`` or ``n``. Other A true or false value specified as either ``y`` or ``n``.
values such as ``t`` or ``f`` are not supported.
Hexadecimal Hexadecimal
A base-16 (integer) value represented by a leading ``0x`` or ``0X`` followed by A base-16 (integer) value represented by a leading ``0x`` or ``0X`` followed by
@ -36,6 +35,51 @@ String
A sequence of UTF-8 characters. String-length limits or specific A sequence of UTF-8 characters. String-length limits or specific
string value restrictions are defined in the option description. string value restrictions are defined in the option description.
.. comment These images are used in generated option documentation
.. |icon-advanced| image:: images/Advanced.svg
:alt: Find this option on the Configurator's Advanced Parameters tab
.. |icon-basic| image:: images/Basic.svg
:alt: Find this option on the Configurator's Basic Parameters tab
.. |icon-not-available| image:: images/Not-available.svg
:alt: This is a hidden option and not user-editable using the Configurator
.. |icon-post-launched-vm| image:: images/Post-launched-VM.svg
:alt: Find this option on a Configurator Post-launched VM tab
.. |icon-pre-launched-vm| image:: images/Pre-launched-VM.svg
:alt: Find this option on a Configurator Pre-launched VM tab
.. |icon-service-vm| image:: images/Service-VM.svg
:alt: Find this option on the Configurator Service VM tab
.. |icon-hypervisor| image:: images/Hypervisor.svg
:alt: Find this option on the Configurator's Hypervisor Global Settings tab
We use icons within an option description to indicate where the option can be
found within the Configurator UI:
.. list-table::
:header-rows: 1
* - **Hypervisor/VM Tab**
- **Basic/Advanced Tab**
* - |icon-hypervisor|
Find this option on the Configurator's **Hypervisor Global Settings** tab
- |icon-basic|
Find this option on the Hypervisor's or VM's **Basic Parameters** tab
* - |icon-pre-launched-vm|
Find this option on a Configurator **Pre-Launched VM** tab
- |icon-advanced|
Find this option on the Hypervisor's or VM's **Advanced Parameters** tab
* - |icon-post-launched-vm|
Find this option on a Configurator **Post-Launched VM** tab
-
* - |icon-service-vm|
Find this option on the Configurator **Service VM** tab
-
-----
.. comment This configdoc.txt is generated during the doc build process .. comment This configdoc.txt is generated during the doc build process
from the acrn config schema files found in misc/config_tools/schema from the acrn config schema files found in misc/config_tools/schema

1
doc/reference/images/Advanced.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="125" height="20" role="img" aria-label="Advanced Parameter"><title>Advanced Parameter</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="125" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#e05d44"/><rect x="0" width="125" height="20" fill="#e05d44"/><rect width="125" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="625" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="1150">Advanced Parameter</text><text x="625" y="140" transform="scale(.1)" fill="#fff" textLength="1150">Advanced Parameter</text></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 965 B

1
doc/reference/images/Basic.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="99" height="20" role="img" aria-label="Basic Parameter"><title>Basic Parameter</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="99" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#007ec6"/><rect x="0" width="99" height="20" fill="#007ec6"/><rect width="99" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="495" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="890">Basic Parameter</text><text x="495" y="140" transform="scale(.1)" fill="#fff" textLength="890">Basic Parameter</text></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 947 B

1
doc/reference/images/Hypervisor.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="69" height="20" role="img" aria-label="Hypervisor"><title>Hypervisor</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="69" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#2b978f"/><rect x="0" width="69" height="20" fill="#2b978f"/><rect width="69" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="345" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="590">Hypervisor</text><text x="345" y="140" transform="scale(.1)" fill="#fff" textLength="590">Hypervisor</text></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 927 B

1
doc/reference/images/Not-available.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="185" height="20" role="img" aria-label="Not available in Configurator UI"><title>Not available in Configurator UI</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="185" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#9f9f9f"/><rect x="0" width="185" height="20" fill="#9f9f9f"/><rect width="185" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="925" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="1750">Not available in Configurator UI</text><text x="925" y="140" transform="scale(.1)" fill="#fff" textLength="1750">Not available in Configurator UI</text></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 1021 B

1
doc/reference/images/Post-launched-VM.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="109" height="20" role="img" aria-label="Post-launched VM"><title>Post-launched VM</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="109" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#998265"/><rect x="0" width="109" height="20" fill="#998265"/><rect width="109" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="545" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="990">Post-launched VM</text><text x="545" y="140" transform="scale(.1)" fill="#fff" textLength="990">Post-launched VM</text></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 955 B

1
doc/reference/images/Pre-launched-VM.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="103" height="20" role="img" aria-label="Pre-launched VM"><title>Pre-launched VM</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="103" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#4c1"/><rect x="0" width="103" height="20" fill="#4c1"/><rect width="103" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="515" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="930">Pre-launched VM</text><text x="515" y="140" transform="scale(.1)" fill="#fff" textLength="930">Pre-launched VM</text></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 945 B

3
doc/reference/images/README Normal file
View File

@ -0,0 +1,3 @@
These icon badges were created using https://shields.io static badges.
Standard colors were used except for the Hypervisor #69BFAD (acrn-lightgreen) and post-launched VM
#998265 (acrn-brown) colors defined in the acrn-custom.css

1
doc/reference/images/Service-VM.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="71" height="20" role="img" aria-label="Service VM"><title>Service VM</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="71" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#dfb317"/><rect x="0" width="71" height="20" fill="#dfb317"/><rect width="71" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="355" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="610">Service VM</text><text x="355" y="140" transform="scale(.1)" fill="#fff" textLength="610">Service VM</text></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 927 B

398
doc/scripts/configdoc.xsl
View File

@ -1,165 +1,226 @@
<?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:acrn="https://projectacrn.org" version="1.0">
<xsl:stylesheet
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="'&#10;'"/>
<xsl:variable name="newline" select="'&#xa;'"/>
<xsl:variable name="section_adornment" select="'#*=-%+@`'"/> <xsl:variable name="section_adornment" select="'#*=-%+@`'"/>
<xsl:variable name="vLower" select="'abcdefghijklmnopqrstuvwxyz'"/>
<xsl:variable name="vLower" select= "'abcdefghijklmnopqrstuvwxyz'"/> <xsl:variable name="vUpper" select="'ABCDEFGHIJKLMNOPQRSTUVWXYZ'"/>
<xsl:variable name="vUpper" select= "'ABCDEFGHIJKLMNOPQRSTUVWXYZ'"/> <!-- xslt script to autogenerate config option documentation -->
<!-- Get things started with the ACRNConfigType element -->
<!--
Visitors of XSD elements
-->
<xsl:template match="/xs:schema"> <xsl:template match="/xs:schema">
<xsl:apply-templates select="xs:complexType[@name='ACRNConfigType']"> <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:with-param name="parent" select="."/>
</xsl:apply-templates> </xsl:apply-templates>
</xsl:template> </xsl:template>
<!-- Walk through all the ACRNConfigType element's children -->
<xsl:template match="xs:complexType[@name='ACRNConfigType']"> <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: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:with-param name="parent" select="."/>
</xsl:apply-templates> </xsl:apply-templates>
</xsl:template> </xsl:template>
<!-- ... and process all the child elements -->
<xsl:template match="xs:element"> <xsl:template match="xs:element">
<xsl:param name="level"/> <xsl:param name="level"/>
<xsl:param name="prefix"/> <xsl:param name="prefix"/>
<xsl:param name="parent"/>
<xsl:variable name="ty"> <xsl:variable name="ty">
<xsl:choose> <xsl:choose>
<xsl:when test="@type"> <xsl:when test="@type">
<xsl:value-of select="@type" /> <xsl:value-of select="@type"/>
</xsl:when> </xsl:when>
<xsl:otherwise> <xsl:otherwise>
<xsl:value-of select=".//xs:alternative[1]/@type" /> <xsl:value-of select=".//xs:alternative[1]/@type"/>
</xsl:otherwise> </xsl:otherwise>
</xsl:choose> </xsl:choose>
</xsl:variable> </xsl:variable>
<!-- dxnamePure and dxname hold the element name with and without spaces converted to underscores -->
<xsl:variable name="dxnamePure">
<xsl:choose>
<xsl:when test=".//descendant::xs:annotation/@acrn:title">
<xsl:value-of select=".//descendant::xs:annotation/@acrn:title"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="@name"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:variable name="dxname">
<xsl:value-of select="translate($dxnamePure,' ','_')"/>
</xsl:variable>
<!-- Only visit elements having complex types. Those having simple types are <!-- Only visit elements having complex types. Those having simple types are
described as an option.. --> described as an option -->
<xsl:choose> <xsl:choose>
<xsl:when test="//xs:complexType[@name=$ty]"> <xsl:when test="//xs:complexType[@name=$ty]">
<!-- for top level sections (level 2) put a begin/end comment for <!-- The section header -->
potential use in rst include directives --> <xsl:if test="$level &lt;= 4">
<xsl:if test="$level = 2"> <xsl:call-template name="section-header">
<xsl:value-of select="concat('.. section-start ', $prefix, @name, $newline)"/> <xsl:with-param name="title" select="$dxnamePure"/>
</xsl:if> <xsl:with-param name="label" select="concat($prefix, $dxname)"/>
<!-- The section header --> <xsl:with-param name="level" select="$level"/>
<xsl:if test="$level &lt;= 4"> </xsl:call-template>
<xsl:call-template name="section-header"> <!-- Description of this menu / entry -->
<xsl:with-param name="title" select="concat($prefix, @name)"/> <xsl:call-template name="print-annotation">
<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:call-template>
<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:call-template>
-->
<xsl:value-of select="$newline"/> <xsl:value-of select="$newline"/>
</xsl:if> <!-- use a sorted glossary to show a sorted list of config options in this section -->
<xsl:value-of select="concat('.. glossary::',$newline,' :sorted:',$newline,$newline)"/>
<!-- Visit the complex type to generate menus and/or entries --> </xsl:if>
<xsl:apply-templates select="//xs:complexType[@name=$ty]"> <!-- Visit the complex type to generate menus and/or entries -->
<xsl:with-param name="level" select="$level"/> <xsl:apply-templates select="//xs:complexType[@name=$ty]">
<xsl:with-param name="name" select="concat($prefix, @name)"/> <xsl:with-param name="level" select="$level"/>
</xsl:apply-templates> <xsl:with-param name="name" select="concat($prefix, $dxname)"/>
<!-- for top level sections (level 2) put a begin/end comment for <xsl:with-param name="parent" select="."/>
potential use in rst include directives --> </xsl:apply-templates>
<xsl:if test="$level = 2"> </xsl:when>
<xsl:value-of select="concat('.. section-end ', $prefix, @name, $newline)"/> <xsl:when test="xs:annotation/@acrn:views=''">
</xsl:if> <!-- don't document elements if not viewable -->
</xsl:when> </xsl:when>
<xsl:otherwise> <xsl:otherwise>
<!-- Write a section header for elements with a simple type --> <!-- No longer writing a section header for elements with a simple type
<xsl:if test="$level = 3"> <xsl:if test="$level = 3">
<xsl:call-template name="section-header"> <xsl:call-template name="section-header">
<xsl:with-param name="title" select="concat($prefix, @name)"/> <xsl:with-param name="title" select="$dxnamePure"/>
<xsl:with-param name="label" select="concat($prefix, @name)"/> <xsl:with-param name="label" select="concat($prefix, $dxname)"/>
<xsl:with-param name="level" select="$level"/> <xsl:with-param name="level" select="$level"/>
</xsl:call-template> </xsl:call-template>
</xsl:if> </xsl:if> -->
<!-- print option as a glossary item -->
<xsl:call-template name="option-header"> <!-- put a sortable character in front of options not available in UI -->
<xsl:with-param name="label" select="concat($prefix, @name)"/> <!-- <xsl:if test="xs:annotation/@acrn:views=''">
</xsl:call-template> <xsl:text> ~</xsl:text>
<xsl:value-of select="$newline"/> </xsl:if> -->
<!-- Print the description, type, and occurrence requirements --> <xsl:value-of select="concat(' ',$dxnamePure,$newline)"/>
<xsl:text> - </xsl:text> <!-- print icons for basic/advanced, hypervisor/VM applicability -->
<xsl:call-template name="print-annotation" > <xsl:variable name="option-icons">
<xsl:with-param name="indent" select="' '"/> <!-- acrn:views describes if this option appears on a "basic" or "advanced" tab, or not at all
</xsl:call-template> when the value is "". If the acrn:views attribute is missing, then the containing parent's
<xsl:choose> acrn:views value is used instead. Similarly for the acrn:applicable-vms attribute. -->
<xsl:when test="//xs:simpleType[@name=$ty]"> <xsl:choose>
<xsl:apply-templates select="//xs:simpleType[@name=$ty]"/> <xsl:when test="contains($prefix,'Hypervisor')">
</xsl:when> <xsl:text>|icon-hypervisor| </xsl:text>
<xsl:when test="starts-with($ty, 'xs:')"> </xsl:when>
<xsl:text> - </xsl:text> <xsl:otherwise>
<xsl:value-of select="concat(translate(substring($ty, 4,1), $vLower, $vUpper), substring($ty,5))"/> <xsl:choose>
<xsl:value-of select="$newline"/> <xsl:when test="count(xs:annotation/@acrn:applicable-vms)=0">
</xsl:when> <xsl:if test="contains($parent/xs:annotation/@acrn:applicable-vms,'pre-launched') or contains($parent/../xs:annotation/@acrn:applicable-vms,'pre-launched') or contains($parent/../../xs:annotation/@acrn:applicable-vms,'pre-launched')">
<xsl:otherwise> <xsl:text>|icon-pre-launched-vm| </xsl:text>
<!-- element doesn't have a named type, check for an unnamed simpleType child --> </xsl:if>
<xsl:apply-templates select="descendant::xs:simpleType"> <xsl:if test="contains($parent/xs:annotation/@acrn:applicable-vms,'post-launched') or contains($parent/../xs:annotation/@acrn:applicable-vms,'post-launched') or contains($parent/../../xs:annotation/@acrn:applicable-vms,'post-launched')">
<xsl:with-param name="level" select="$level"/> <xsl:text>|icon-post-launched-vm| </xsl:text>
<xsl:with-param name="prefix" select="''"/> </xsl:if>
</xsl:apply-templates> <xsl:if test="contains($parent/xs:annotation/@acrn:applicable-vms,'service-vm') or contains($parent/../xs:annotation/@acrn:applicable-vms,'service-vm') or contains($parent/../../xs:annotation/@acrn:applicable-vms,'service-vm')">
</xsl:otherwise> <xsl:text>|icon-service-vm| </xsl:text>
</xsl:choose> </xsl:if>
<!-- removing occurs info for now </xsl:when>
<xsl:text> - </xsl:text> <xsl:otherwise>
<xsl:call-template name="print-occurs" > <xsl:if test="contains(xs:annotation/@acrn:applicable-vms,'pre-launched')">
<xsl:with-param name="name" select="@name"/> <xsl:text>|icon-pre-launched-vm| </xsl:text>
</xsl:call-template> </xsl:if>
<xsl:if test="contains(xs:annotation/@acrn:applicable-vms,'post-launched')">
<xsl:text>|icon-post-launched-vm| </xsl:text>
</xsl:if>
<xsl:if test="contains(xs:annotation/@acrn:applicable-vms,'service-vm')">
<xsl:text>|icon-service-vm| </xsl:text>
</xsl:if>
</xsl:otherwise>
</xsl:choose>
</xsl:otherwise>
</xsl:choose>
<xsl:text>/ </xsl:text>
<xsl:if test="xs:annotation/@acrn:views=''">
<xsl:text>|icon-not-available| </xsl:text>
</xsl:if>
<xsl:if test="count(xs:annotation/@acrn:views)=0">
<xsl:if test="contains($parent/xs:annotation/@acrn:views,'basic') or contains($parent/../xs:annotation/@acrn:views,'basic') or contains($parent/../../xs:annotation/@acrn:views,'basic')">
<xsl:text>|icon-basic| </xsl:text>
</xsl:if>
<xsl:if test="contains($parent/xs:annotation/@acrn:views,'advanced') or contains($parent/../xs:annotation/@acrn:views,'advanced') or contains($parent/../../xs:annotation/@acrn:views,'advanced')">
<xsl:text>|icon-advanced| </xsl:text>
</xsl:if>
</xsl:if>
<xsl:if test="contains(xs:annotation/@acrn:views,'basic')">
<xsl:text>|icon-basic| </xsl:text>
</xsl:if>
<xsl:if test="contains(xs:annotation/@acrn:views,'advanced')">
<xsl:text>|icon-advanced| </xsl:text>
</xsl:if>
</xsl:variable>
<xsl:if test="$option-icons!=''">
<xsl:value-of select="concat(' ',$option-icons,$newline)"/>
</xsl:if>
<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:call-template>
<xsl:choose>
<xsl:when test="//xs:simpleType[@name=$ty]">
<xsl:apply-templates select="//xs:simpleType[@name=$ty]">
<xsl:with-param name="level" select="$level"/>
<xsl:with-param name="prefix" select="''"/>
<xsl:with-param name="parent" select="$parent"/>
</xsl:apply-templates>
</xsl:when>
<xsl:when test="starts-with($ty, 'xs:')">
<xsl:text> - </xsl:text>
<!-- if unnamed type such as xs:string or xs:integer, print that simple type name with an uppercase first letter -->
<xsl:value-of select="concat(translate(substring($ty, 4,1), $vLower, $vUpper), substring($ty,5),' value')"/>
<xsl:value-of select="$newline"/>
</xsl:when>
<xsl:otherwise>
<!-- 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:with-param name="parent" select="$parent"/>
</xsl:apply-templates>
</xsl:otherwise>
</xsl:choose>
<!-- Removed printing occurrance information
<xsl:text> - </xsl:text>
<xsl:call-template name="print-occurs">
<xsl:with-param name="name" select="$dxnamePure"/>
</xsl:call-template> -->
<xsl:value-of select="$newline"/> <xsl:value-of select="$newline"/>
-->
</xsl:otherwise> </xsl:otherwise>
</xsl:choose> </xsl:choose>
</xsl:template> </xsl:template>
<xsl:template match="xs:complexType"> <xsl:template match="xs:complexType">
<xsl:param name="level"/> <xsl:param name="level"/>
<xsl:param name="name"/> <xsl:param name="name"/>
<xsl:param name="parent"/>
<!-- Visit the sub-menus --> <!-- Visit the sub-menus -->
<xsl:apply-templates select="descendant::xs:element"> <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:with-param name="parent" select="$parent"/>
</xsl:apply-templates> </xsl:apply-templates>
</xsl:template> </xsl:template>
<xsl:template match="xs:simpleType"> <xsl:template match="xs:simpleType">
<xsl:text> - </xsl:text> <xsl:text> - </xsl:text>
<xsl:call-template name="print-annotation" > <xsl:choose>
<xsl:with-param name="indent" select="' '"/> <xsl:when test="xs:annotation/xs:documentation">
</xsl:call-template> <xsl:call-template name="print-annotation">
<xsl:with-param name="indent" select="' '"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:text>No type annotation found</xsl:text>
<xsl:value-of select="$newline"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template> </xsl:template>
<xsl:template name="print-occurs"> <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 <!-- use the min/maxOccurs data to figure out if this is an optional
item, and how many occurrences are allowed --> item, and how many occurrences are allowed -->
<xsl:variable name="min"> <xsl:variable name="min">
<xsl:choose> <xsl:choose>
@ -169,7 +230,6 @@
<xsl:otherwise>1</xsl:otherwise> <xsl:otherwise>1</xsl:otherwise>
</xsl:choose> </xsl:choose>
</xsl:variable> </xsl:variable>
<xsl:variable name="max"> <xsl:variable name="max">
<xsl:choose> <xsl:choose>
<xsl:when test="@maxOccurs"> <xsl:when test="@maxOccurs">
@ -178,10 +238,9 @@
<xsl:otherwise>1</xsl:otherwise> <xsl:otherwise>1</xsl:otherwise>
</xsl:choose> </xsl:choose>
</xsl:variable> </xsl:variable>
<xsl:text>The ``</xsl:text>
<xsl:text>The **</xsl:text>
<xsl:value-of select="$name"/> <xsl:value-of select="$name"/>
<xsl:text>** option is </xsl:text> <xsl:text>`` option is </xsl:text>
<xsl:choose> <xsl:choose>
<xsl:when test="$min = 0"> <xsl:when test="$min = 0">
<xsl:text>optional</xsl:text> <xsl:text>optional</xsl:text>
@ -190,13 +249,12 @@
<xsl:text>required</xsl:text> <xsl:text>required</xsl:text>
</xsl:otherwise> </xsl:otherwise>
</xsl:choose> </xsl:choose>
<xsl:text> and with </xsl:text> <xsl:text> (</xsl:text>
<xsl:choose> <xsl:choose>
<xsl:when test="($min = $max) or ($min = 0)"> <xsl:when test="($min = $max) or ($min = 0)">
<xsl:value-of select="$max"/> <xsl:value-of select="$max"/>
<xsl:text> occurrence</xsl:text> <xsl:text> occurrence</xsl:text>
<xsl:if test="$max &gt; 1"> <xsl:if test="$max &gt; 1 or $max='unbounded'">
<xsl:text>s</xsl:text> <xsl:text>s</xsl:text>
</xsl:if> </xsl:if>
</xsl:when> </xsl:when>
@ -207,10 +265,9 @@
<xsl:text> occurrences</xsl:text> <xsl:text> occurrences</xsl:text>
</xsl:otherwise> </xsl:otherwise>
</xsl:choose> </xsl:choose>
<xsl:text>.</xsl:text> <xsl:text>).</xsl:text>
<xsl:value-of select="$newline"/> <xsl:value-of select="$newline"/>
</xsl:template> </xsl:template>
<xsl:template name="print-annotation"> <xsl:template name="print-annotation">
<xsl:param name="indent"/> <xsl:param name="indent"/>
<!-- append an (Optional) annotation if minOccurs=0) --> <!-- append an (Optional) annotation if minOccurs=0) -->
@ -218,11 +275,16 @@
<xsl:choose> <xsl:choose>
<xsl:when test="@minOccurs"> <xsl:when test="@minOccurs">
<xsl:if test="@minOccurs = 0"> <xsl:if test="@minOccurs = 0">
<xsl:text> *(Optional)*</xsl:text> <xsl:text> *(Optional)*</xsl:text>
</xsl:if>
<xsl:if test="@minOccurs != 0">
<xsl:text> *(Required)**</xsl:text>
</xsl:if> </xsl:if>
</xsl:when> </xsl:when>
<!-- could show (Required) here instead, but it seemed too noisy --> <!-- could show (Required) here instead, but it seemed too noisy -->
<xsl:otherwise><xsl:text></xsl:text></xsl:otherwise> <xsl:otherwise>
<xsl:text/>
</xsl:otherwise>
</xsl:choose> </xsl:choose>
</xsl:variable> </xsl:variable>
<!-- append a default value annotation if default was defined --> <!-- append a default value annotation if default was defined -->
@ -231,16 +293,23 @@
<xsl:when test="@default"> <xsl:when test="@default">
<xsl:value-of select="concat(' (Default value is ``', @default, '``)')"/> <xsl:value-of select="concat(' (Default value is ``', @default, '``)')"/>
</xsl:when> </xsl:when>
<xsl:otherwise><xsl:text></xsl:text></xsl:otherwise> <xsl:otherwise>
<xsl:text/>
</xsl:otherwise>
</xsl:choose> </xsl:choose>
</xsl:variable> </xsl:variable>
<xsl:choose> <xsl:choose>
<xsl:when test="xs:annotation"> <xsl:when test="xs:annotation">
<xsl:call-template name="printIndented"> <xsl:call-template name="printIndented">
<xsl:with-param name="text" select="concat(xs:annotation/xs:documentation, $optional, $default)"/> <xsl:with-param name="text" select="concat(xs:annotation/xs:documentation[1], $default)"/>
<xsl:with-param name="indent" select="$indent"/> <xsl:with-param name="indent" select="$indent"/>
</xsl:call-template> </xsl:call-template>
<!-- append a second xs:annotation if found. This allows more content for the documentation that
won't be included in the Configurator tooltip -->
<xsl:call-template name="printIndented">
<xsl:with-param name="text" select="concat($newline, xs:annotation/xs:documentation[2])"/>
<xsl:with-param name="indent" select="$indent"/>
</xsl:call-template>
</xsl:when> </xsl:when>
<xsl:otherwise> <xsl:otherwise>
<!-- <xsl:text>&lt;description is missing &gt;</xsl:text> --> <!-- <xsl:text>&lt;description is missing &gt;</xsl:text> -->
@ -248,23 +317,20 @@
</xsl:otherwise> </xsl:otherwise>
</xsl:choose> </xsl:choose>
</xsl:template> </xsl:template>
<!-- <!--
Library Routines Library Routines
--> -->
<xsl:template name="repeat"> <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:if test="$times &gt; 0">
<xsl:value-of select="$string"/> <xsl:value-of select="$string"/>
<xsl:call-template name="repeat"> <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:call-template>
</xsl:if> </xsl:if>
</xsl:template> </xsl:template>
<xsl:template name="section-header"> <xsl:template name="section-header">
<xsl:param name="title"/> <xsl:param name="title"/>
<xsl:param name="label"/> <xsl:param name="label"/>
@ -275,51 +341,39 @@
<xsl:value-of select="concat($title, $newline)"/> <xsl:value-of select="concat($title, $newline)"/>
<xsl:call-template name="repeat"> <xsl:call-template name="repeat">
<xsl:with-param name="string"> <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>
<xsl:with-param name="times" select="string-length($title)"/> <xsl:with-param name="times" select="string-length($title)"/>
</xsl:call-template> </xsl:call-template>
<xsl:value-of select="concat($newline, $newline)"/> <xsl:value-of select="concat($newline, $newline)"/>
</xsl:template> </xsl:template>
<xsl:template name="printIndented">
<xsl:template name="option-header"> <xsl:param name="text"/>
<xsl:param name="label"/> <xsl:param name="indent"/>
<!-- we're using the reST option directive for creating linkable <!-- Handle multi-line documentation text and indent it properly for
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:template>
<xsl:template name="printIndented">
<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 the bullet list display we're using for node descriptions (but not for
heading descriptions --> heading descriptions -->
<xsl:if test="$text"> <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:choose>
<xsl:when test="$thisLine or $nextLine"> <xsl:when test="$thisLine or $nextLine">
<!-- $text contains at least one newline, and there's more coming so print it --> <!-- $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 --> <!-- watch for two newlines in a row and avoid writing the indent -->
<xsl:if test="substring-before(concat($nextLine, $newline), $newline)" > <xsl:if test="substring-before(concat($nextLine, $newline), $newline)">
<xsl:value-of select="$indent"/> <xsl:value-of select="$indent"/>
</xsl:if> </xsl:if>
<!-- and recurse to process the rest --> <!-- and recurse to process the rest -->
<xsl:call-template name="printIndented"> <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:call-template>
</xsl:when> </xsl:when>
<xsl:otherwise> <xsl:otherwise>
<xsl:value-of select="concat($text, $newline)"/> <xsl:value-of select="concat($text, $newline)"/>
</xsl:otherwise> </xsl:otherwise>
</xsl:choose> </xsl:choose>
</xsl:if> </xsl:if>
</xsl:template> </xsl:template>
</xsl:stylesheet> </xsl:stylesheet>

28
doc/static/acrn-custom.css vendored
View File

@ -389,3 +389,31 @@ html.writer-html5 .rst-content table.docutils td p {
margin-bottom: 0; margin-bottom: 0;
font-size: .9rem; font-size: .9rem;
} }
/* Simulate look of an option directive on glossary items (particularly used on
* config option listings so we can use a glossary to sort config options within
* a section of options*/
div#scenario-configuration-options dl.glossary dt {
display: table;
margin: 6px 10px;
font-weight: bold;
color: #000;
line-height: normal;
background: #e7f2fa;
color: #2980b9;
border-top: 3px solid #6ab0de;
padding: 6px;
position: relative;
}
div#scenario-configuration-options dl.glossary dt {
float: left;
clear: left;
}
div#scenario-configuration-options dl.glossary dd>p {
padding-top: 12px;
line-height: normal;
clear: right;
}
div#scenario-configuration-options dl.glossary dd ul {
clear: both;
}

5
doc/static/acrn-custom.js vendored
View File

@ -6,4 +6,9 @@ $(document).ready(function(){
/* open external links in a new tab */ /* open external links in a new tab */
$('a[class*=external]').attr({target: '_blank', rel: 'noopener'}); $('a[class*=external]').attr({target: '_blank', rel: 'noopener'});
/* copy image alt tags in config option page as title for hover text tool tip by browser */
$("div#scenario-configuration-options img[alt]").each(function(){
$(this).attr('title', $(this).attr('alt'));
});
}); });

10
doc/tutorials/nvmx_virtualization.rst
View File

@ -124,7 +124,7 @@ with these settings:
#. Configure system level features: #. Configure system level features:
- Edit :option:`hv.FEATURES.SCHEDULER` to ``SCHED_NOOP`` to disable CPU sharing - Edit ``hv.features.scheduler`` to ``SCHED_NOOP`` to disable CPU sharing
.. code-block:: xml .. code-block:: xml
:emphasize-lines: 3,18 :emphasize-lines: 3,18
@ -150,11 +150,11 @@ with these settings:
#. In each guest VM configuration: #. In each guest VM configuration:
- Edit :option:`vm.nested_virtualization_support` on the Service VM section and set it to `y` - Edit ``vm.nested_virtualization_support`` on the Service VM section and set it to `y`
to enable the nested virtualization feature on the Service VM. to enable the nested virtualization feature on the Service VM.
- Edit :option:`vm.lapic_passthrough` and set it to `y` to enable local - Edit ``vm.lapic_passthrough`` and set it to `y` to enable local
APIC passthrough on the Service VM. APIC passthrough on the Service VM.
- Edit :option:`vm.cpu_affinity.pcpu_id` to assign ``pCPU`` IDs to run the Service VM. If you are - Edit ``vm.cpu_affinity.pcpu_id`` to assign ``pCPU`` IDs to run the Service VM. If you are
using debug build and need the hypervisor console, don't assign using debug build and need the hypervisor console, don't assign
``pCPU0`` to the Service VM. ``pCPU0`` to the Service VM.
@ -179,7 +179,7 @@ with these settings:
the PCI-vUART for the Service VM. Refer to :ref:`Enable vUART Configurations <vuart_config>` the PCI-vUART for the Service VM. Refer to :ref:`Enable vUART Configurations <vuart_config>`
for more details about VUART configuration. for more details about VUART configuration.
- Set :option:`vm.console_vuart` to ``PCI`` - Set ``vm.console_vuart`` to ``PCI``
.. code-block:: xml .. code-block:: xml
:emphasize-lines: 1 :emphasize-lines: 1

10
doc/tutorials/vcat_configuration.rst
View File

@ -13,12 +13,12 @@ into XML in the scenario file:
#. Configure system level features: #. Configure system level features:
- Edit :option:`hv.FEATURES.RDT.RDT_ENABLED` to `y` to enable RDT - Edit ``hv.FEATURES.RDT.RDT_ENABLED`` to `y` to enable RDT
- Edit :option:`hv.FEATURES.RDT.CDP_ENABLED` to `n` to disable CDP. - Edit ``hv.FEATURES.RDT.CDP_ENABLED`` to `n` to disable CDP.
vCAT requires CDP to be disabled. vCAT requires CDP to be disabled.
- Edit :option:`hv.FEATURES.RDT.VCAT_ENABLED` to `y` to enable vCAT - Edit ``hv.FEATURES.RDT.VCAT_ENABLED`` to `y` to enable vCAT
.. code-block:: xml .. code-block:: xml
:emphasize-lines: 3,4,5 :emphasize-lines: 3,4,5
@ -34,9 +34,9 @@ into XML in the scenario file:
#. In each Guest VM configuration: #. In each Guest VM configuration:
- Edit :option:`vm.virtual_cat_support` to 'y' to enable the vCAT feature on the VM. - Edit ``vm.virtual_cat_support`` to 'y' to enable the vCAT feature on the VM.
- Edit :option:`vm.clos.vcpu_clos` to assign COS IDs to the VM. - Edit ``vm.clos.vcpu_clos`` to assign COS IDs to the VM.
If ``GUEST_FLAG_VCAT_ENABLED`` is not specified for a VM (abbreviated as RDT VM): If ``GUEST_FLAG_VCAT_ENABLED`` is not specified for a VM (abbreviated as RDT VM):
``vcpu_clos`` is per CPU in a VM and it configures each CPU in a VM to a desired COS ID. ``vcpu_clos`` is per CPU in a VM and it configures each CPU in a VM to a desired COS ID.