github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-07-19 01:40:17 +00:00
Code Issues Projects Releases Wiki Activity

doc: integrate config xsl transform into doc build

Browse Source 
Documentation for the scenario XML configuration options is pulled from the
schema definition files (xsd) maintained in the misc/config_tools/schema
folder.  Update the doc build process to generate and incorporate the
option documentation.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
Yang, Yu-chu 2021-01-28 10:14:00 +08:00 committed by wenlingz
parent fa01261552
commit f1c339df2a
8 changed files with 599 additions and 275 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/Makefile
View File

@ -48,6 +48,9 @@ doxy: copy-to-sourcedir
content: copy-to-sourcedir content: copy-to-sourcedir
$(Q)scripts/extract_content.py $(SOURCEDIR) misc $(Q)scripts/extract_content.py $(SOURCEDIR) misc
$(Q)mkdir -p $(SOURCEDIR)/misc/config_tools/schema
$(Q)rsync -rt ../misc/config_tools/schema/*.xsd $(SOURCEDIR)/misc/config_tools/schema
$(Q)xsltproc -xinclude ./scripts/configdoc.xsl $(SOURCEDIR)/misc/config_tools/schema/config.xsd > $(SOURCEDIR)/reference/configdoc.txt
kconfig: copy-to-sourcedir kconfig: copy-to-sourcedir
$(Q)srctree=../hypervisor \ $(Q)srctree=../hypervisor \

1
doc/develop.rst
View File

@ -14,6 +14,7 @@ Configuration and Tools
:maxdepth: 1 :maxdepth: 1
tutorials/acrn_configuration_tool tutorials/acrn_configuration_tool
reference/config-options
reference/kconfig/index reference/kconfig/index
user-guides/hv-parameters user-guides/hv-parameters
user-guides/kernel-parameters user-guides/kernel-parameters

41
doc/reference/config-options.rst Normal file
View File

@ -0,0 +1,41 @@
.. _scenario-config-options:
Scenario Configuration Options
##############################
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.
.. contents::
:local:
:depth: 2
Common option value types
*************************
Within this option documentation, we refer to some common type
definitions:
Boolean
A true or false value specified as either ``y`` or ``n``. Other
values such as ``t`` or ``f`` are not supported.
Hexadecimal
A base-16 (integer) value represented by a leading ``0x`` or ``0X`` followed by
one or more characters ``0`` to ``9``, ``a`` to ``f``, or ``A`` to ``F``.
Integer
A base-10 value represented by the characters ``0`` to ``9``. The
first character must not be a ``0``. Only positive values are
expected.
String
A sequence of UTF-8 characters. String-length limits or specific
string value restrictions are defined in the option description.
.. comment This configdoc.txt is generated during the doc build process
from the acrn config schema files found in misc/config_tools/schema
.. include:: configdoc.txt

278
doc/scripts/configdoc.xsl Normal file
View File

@ -0,0 +1,278 @@
<?xml version="1.0" encoding="utf-8"?>
<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:variable name="newline" select="'&#xa;'" />
<xsl:variable name="section_adornment" select="'#*=-%+@`'" />
<!--
Visitors of XSD elements
-->
<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:apply-templates>
</xsl:template>
<xsl:template match="xs:complexType[@name='ACRNConfigType']">
<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:apply-templates>
</xsl:template>
<xsl:template match="xs:element">
<xsl:param name="level" />
<xsl:param name="prefix" />
<xsl:variable name="ty" select="@type" />
<!-- Only visit elements having complex types. Those having simple types are
described as an option.. -->
<xsl:choose>
<xsl:when test="//xs:complexType[@name=$ty]">
<!-- for top level sections (level 2) put a begin/end comment for
potential use in rst include directives -->
<xsl:if test="$level = 2">
<xsl:value-of select="concat('.. section-start ', $prefix, @name, $newline)"/>
</xsl:if>
<!-- 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:call-template>
<!-- Description of this menu / entry -->
<xsl:call-template name="print-annotation" >
<xsl:with-param name="indent" select="''" />
</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: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:apply-templates>
<!-- for top level sections (level 2) put a begin/end comment for
potential use in rst include directives -->
<xsl:if test="$level = 2">
<xsl:value-of select="concat('.. section-end ', $prefix, @name, $newline)"/>
</xsl:if>
</xsl:when>
<xsl:otherwise>
<xsl:call-template name="option-header">
<xsl:with-param name="label" select="concat($prefix, @name)" />
</xsl:call-template>
<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: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:when>
<xsl:otherwise>
<xsl:text> - </xsl:text>
<xsl:value-of select="$ty" />
<xsl:value-of select="$newline" />
</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:call-template>
<xsl:value-of select="$newline" />
-->
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template match="xs:complexType">
<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: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:call-template>
</xsl:template>
<xsl:template name="print-occurs">
<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:when>
<xsl:otherwise>1</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:variable name="max">
<xsl:choose>
<xsl:when test="@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:text>** option is </xsl:text>
<xsl:choose>
<xsl:when test="$min = 0">
<xsl:text>optional</xsl:text>
</xsl:when>
<xsl:otherwise>
<xsl:text>required</xsl:text>
</xsl:otherwise>
</xsl:choose>
<xsl:text> and with </xsl:text>
<xsl:choose>
<xsl:when test="($min = $max) or ($min = 0)">
<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:text> to </xsl:text>
<xsl:value-of select="$max" />
<xsl:text> occurrences</xsl:text>
</xsl:otherwise>
</xsl:choose>
<xsl:text>.</xsl:text>
<xsl:value-of select="$newline" />
</xsl:template>
<xsl:template name="print-annotation">
<xsl:param name="indent" />
<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:call-template>
</xsl:when>
<xsl:otherwise>
<!-- <xsl:text>&lt;description is missing &gt;</xsl:text> -->
<xsl:value-of select="$newline" />
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!--
Library Routines
-->
<xsl:template name="repeat">
<xsl:param name="string" />
<xsl:param name="times" />
<xsl:if test="$times > 0">
<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:call-template>
</xsl:if>
</xsl:template>
<xsl:template name="section-header">
<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:if>
<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:with-param>
<xsl:with-param name="times" select="string-length($title)" />
</xsl:call-template>
<xsl:value-of select="concat($newline, $newline)" />
</xsl:template>
<xsl:template name="option-header">
<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: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
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: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)" />
<!-- 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: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:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="concat($text, $newline)" />
</xsl:otherwise>
</xsl:choose>
</xsl:if>
</xsl:template>
</xsl:stylesheet>

4
doc/scripts/genrest.py
View File

@ -50,8 +50,8 @@ def expr_str(expr):
INDEX_RST_HEADER = """.. _configuration: INDEX_RST_HEADER = """.. _configuration:
Configuration Symbol Reference Kconfig Symbol Reference
############################## ########################
Introduction Introduction
************ ************

271
doc/tutorials/acrn-config-details.txt Normal file
View File

@ -0,0 +1,271 @@
``hv``:
Specify the global attributes for all VMs.
``RELEASE`` (a child node of ``DEBUG_OPTIONS``):
Specify the final build is for Release or Debug.
``SERIAL_CONSOLE`` (a child node of ``DEBUG_OPTIONS``):
Specify the host serial device is used for hypervisor debugging.
This configuration is valid only if Service VM ``legacy_vuart0``
is enabled. Leave this field empty if Service VM ``console_vuart``
is enabled. Using ``bootargs`` for ``console_vuart`` configuration.
``MEM_LOGLEVEL`` (a child node of ``DEBUG_OPTIONS``):
Specify the default log level in memory.
``NPK_LOGLEVEL`` (a child node of ``DEBUG_OPTIONS``):
Specify the default log level for the hypervisor NPK log.
``CONSOLE_LOGLEVEL`` (a child node of ``DEBUG_OPTIONS``):
Specify the default log level on the serial console.
``LOG_DESTINATION`` (a child node of ``DEBUG_OPTIONS``):
Specify the bitmap of consoles where logs are printed.
``LOG_BUF_SIZE`` (a child node of ``DEBUG_OPTIONS``):
Specify the capacity of the log buffer for each physical CPU.
``RELOC`` (a child node of ``FEATURES``):
Specify whether the hypervisor image relocation is enabled on booting.
``SCHEDULER`` (a child node of ``FEATURES``):
Specify the CPU scheduler used by the hypervisor.
Supported schedulers are: ``SCHED_NOOP``, ``SCHED_BVT`` and ``SCHED_IORR``.
``MULTIBOOT2`` (a child node of ``FEATURES``):
Specify whether the ACRN hypervisor image can be booted using the
multiboot2 protocol. If not set, GRUB's multiboot2 is not available as a
boot option.
``RDT_ENABLED`` (a child node of ``FEATURES/RDT``):
Specify whether to enable the Resource Director Technology (RDT)
allocation feature. Set to 'y' to enable the feature or 'n' to disable it.
The 'y' will be ignored when hardware does not support RDT.
``CDP_ENABLED`` (a child node of ``FEATURES/RDT``):
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.
``CLOS_MASK`` (a child node of ``FEATURES/RDT``):
Specify the cache capacity bitmask for the CLOS; only continuous '1' bits
are allowed. The value will be ignored when hardware does not support RDT.
``HYPERV_ENABLED`` (a child node of ``FEATURES``):
Specify whether Hyper-V is enabled.
``IOMMU_ENFORCE_SNP`` (a child node of ``FEATURES``):
Specify whether IOMMU enforces snoop behavior of the DMA operation.
``ACPI_PARSE_ENABLED`` (a child node of ``FEATURES``):
Specify whether ACPI runtime parsing is enabled.
``L1D_VMENTRY_ENABLED`` (a child node of ``FEATURES``):
Specify whether the L1 cache flush before VM entry is enabled.
``MCE_ON_PSC_DISABLED`` (a child node of ``FEATURE``):
Specify whether force to disable software workaround for Machine Check
Error on Page Size Change is enabled.
``IVSHMEM`` (a child node of ``FEATURE``):
Specify the inter-VM shared memory configuration
``IVSHMEM_ENABLED`` (a child node of ``FEATURE/IVSHMEM``):
Specify if the inter-VM shared memory feature is enabled.
``IVSHMEM_REGION`` (a child node of ``FEATURE/IVSHMEM``):
Specify a comma-separated list of the inter-VM shared memory region name,
size, and VM IDs that may communicate using this shared region.
* Prefix the region ``name`` with ``hv:/`` (for an hv-land solution).
(See :ref:`ivshmem-hld` for details.)
* Specify the region ``size`` in MB, and a power of 2 (e.g., 2, 4, 8, 16)
up to 512.
* Specify all VM IDs that may use this shared memory area,
separated by a ``:``, for example, ``0:2`` (to share this area between
VMs 0 and 2), or ``0:1:2`` (to let VMs 0, 1, and 2 share this area).
``STACK_SIZE`` (a child node of ``MEMORY``):
Specify the size of stacks used by physical cores. Each core uses one stack
for normal operations and another three for specific exceptions.
``HV_RAM_SIZE`` (a child node of ``MEMORY``):
Specify the size of the RAM region used by the hypervisor.
``LOW_RAM_SIZE`` (a child node of ``MEMORY``):
Specify the size of the RAM region below address 0x10000, starting from address 0x0.
``SOS_RAM_SIZE`` (a child node of ``MEMORY``):
Specify the size of the Service OS VM RAM region.
``UOS_RAM_SIZE`` (a child node of ``MEMORY``):
Specify the size of the User OS VM RAM region.
``PLATFORM_RAM_SIZE`` (a child node of ``MEMORY``):
Specify the size of the physical platform RAM region.
``IOMMU_BUS_NUM`` (a child node of ``CAPACITIES``):
Specify the highest PCI bus ID used during IOMMU initialization.
``MAX_IR_ENTRIES`` (a child node of ``CAPACITIES``):
Specify the maximum number of Interrupt Remapping Entries.
``MAX_IOAPIC_NUM`` (a child node of ``CAPACITIES``):
Specify the maximum number of IOAPICs.
``MAX_PCI_DEV_NUM`` (a child node of ``CAPACITIES``):
Specify the maximum number of PCI devices.
``MAX_IOAPIC_LINES`` (a child node of ``CAPACITIES``):
Specify the maximum number of interrupt lines per IOAPIC.
``MAX_PT_IRQ_ENTRIES`` (a child node of ``CAPACITIES``):
Specify the maximum number of interrupt sources for PT devices.
``MAX_MSIX_TABLE_NUM`` (a child node of ``CAPACITIES``):
Specify the maximum number of MSI-X tables per device.
``MAX_EMULATED_MMIO`` (a child node of ``CAPACITIES``):
Specify the maximum number of emulated MMIO regions.
``GPU_SBDF`` (a child node of ``MISC_CFG``):
Specify the Segment, Bus, Device, and function of the GPU.
``vm``:
Specify the VM with VMID by its ``id`` attribute.
``vm_type``:
Current supported VM types are:
- ``SAFETY_VM`` pre-launched Safety VM
- ``PRE_STD_VM`` pre-launched Standard VM
- ``SOS_VM`` pre-launched Service VM
- ``POST_STD_VM`` post-launched Standard VM
- ``POST_RT_VM`` post-launched real-time capable VM
- ``KATA_VM`` post-launched Kata Container VM
``name`` (a child node of ``vm``):
Specify the VM name shown in the hypervisor console command: vm_list.
``guest_flags``:
Select all applicable flags for the VM:
- ``GUEST_FLAG_SECURE_WORLD_ENABLED`` specify whether 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
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)
``cpu_affinity``:
List of pCPU: the guest VM is allowed to create vCPU from all or a subset of this list.
``base`` (a child node of ``epc_section``):
SGX Enclave Page Cache section base; must be page aligned.
``size`` (a child node of ``epc_section``):
SGX Enclave Page Cache section size in bytes; must be page aligned.
``clos``:
Class of Service for Cache Allocation Technology settings. Refer to :ref:`hv_rdt` for details.
``start_hpa`` (a child node of ``memory``):
The start physical address in host for the VM.
``size`` (a child node of ``memory``):
The memory size in bytes for the VM.
``name`` (a child node of ``os_config``):
Specify the OS name of VM; currently, it is not referenced by the hypervisor code.
``kern_type`` (a child node of ``os_config``):
Specify the kernel image type so that the hypervisor can load it correctly.
Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.
``kern_mod`` (a child node of ``os_config``):
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`` (a child node of ``os_config``):
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`` (a child node of ``os_config``):
For internal use only and is not configurable. Specify the kernel boot arguments
in ``bootargs`` under the parent of ``board_private``.
``kern_load_addr`` (a child node of ``os_config``):
The loading address in host memory for the VM kernel.
``kern_entry_addr`` (a child node of ``os_config``):
The entry address in host memory for the VM kernel.
``legacy_vuart``:
Specify the vUART (aka COM) with the vUART ID by its ``id`` attribute.
Refer to :ref:`vuart_config` for detailed vUART settings.
``console_vuart``:
Specify the console vUART (aka PCI based vUART) with the vUART ID by
its ``id`` attribute.
Refer to :ref:`vuart_config` for detailed vUART settings.
``communication_vuart``:
Specify the communication vUART (aka PCI based vUART) with the vUART ID by
its ``id`` attribute.
Refer to :ref:`vuart_config` for detailed vUART settings.
``type`` (a child node of ``legacy_vuart``):
vUART (aka COM) type; currently only supports the legacy PIO mode.
``base`` (a child node of ``legacy_vuart``, ``console_vuart``, and ``communication_vuart``):
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.
console and communication vUART (A.K.A PCI based vUART) enabling switch.
Enable by specifying PCI_VUART; disable by returning INVALID_PCI_BASE.
``irq`` (a child node of ``legacy_vuart``):
vCOM IRQ.
``target_vm_id`` (a child node of ``legacy_vuart1``, ``communication_vuart``):
COM2 is used for VM communications. When it is enabled, specify which
target VM the current VM connects to.
``communication_vuart`` is used for VM communications. When it is enabled, specify
which target VM the current VM connects to.
``target_uart_id`` (a child node of ``legacy_vuart1`` and ``communication_vuart``):
Target vUART ID to which the vCOM2 connects.
Target vUART ID to which the ``communication_vuart`` connects.
``pci_dev_num``:
PCI devices number of the VM; it is hard-coded for each scenario so it
is not configurable for now.
``pci_devs``:
PCI devices list of the VM; it is hard-coded for each scenario so it
is not configurable for now.
``mmio_resources``:
MMIO resources to passthrough.
``TPM2`` (a child node of ``mmio_resources``):
TPM2 device to passthrough.
``p2sb`` (a child node of ``mmio_resources``):
Exposing the P2SB (Primary-to-Sideband) bridge to the pre-launched VM.
``pt_intx``:
Forward specific IOAPIC interrupts (with interrupt line remapping) to the pre-launched VM.
``board_private``:
Stores scenario-relevant board configuration.
``rootfs`` (a child node of ``board_private``):
rootfs for the Linux kernel.
``bootargs`` (a child node of ``board_private``):
Specify kernel boot arguments.

272
doc/tutorials/acrn_configuration_tool.rst
View File

@ -100,278 +100,8 @@ and ``scenario`` attributes:
<acrn-config board="BOARD" scenario="SCENARIO"> <acrn-config board="BOARD" scenario="SCENARIO">
Additional scenario XML elements: See :ref:`scenario-config-options` for a full explanation of available scenario XML elements.
``hv``:
Specify the global attributes for all VMs.
``RELEASE`` (a child node of ``DEBUG_OPTIONS``):
Specify the final build is for Release or Debug.
``SERIAL_CONSOLE`` (a child node of ``DEBUG_OPTIONS``):
Specify the host serial device is used for hypervisor debugging.
This configuration is valid only if Service VM ``legacy_vuart0``
is enabled. Leave this field empty if Service VM ``console_vuart``
is enabled. Using ``bootargs`` for ``console_vuart`` configuration.
``MEM_LOGLEVEL`` (a child node of ``DEBUG_OPTIONS``):
Specify the default log level in memory.
``NPK_LOGLEVEL`` (a child node of ``DEBUG_OPTIONS``):
Specify the default log level for the hypervisor NPK log.
``CONSOLE_LOGLEVEL`` (a child node of ``DEBUG_OPTIONS``):
Specify the default log level on the serial console.
``LOG_DESTINATION`` (a child node of ``DEBUG_OPTIONS``):
Specify the bitmap of consoles where logs are printed.
``LOG_BUF_SIZE`` (a child node of ``DEBUG_OPTIONS``):
Specify the capacity of the log buffer for each physical CPU.
``RELOC`` (a child node of ``FEATURES``):
Specify whether the hypervisor image relocation is enabled on booting.
``SCHEDULER`` (a child node of ``FEATURES``):
Specify the CPU scheduler used by the hypervisor.
Supported schedulers are: ``SCHED_NOOP``, ``SCHED_BVT`` and ``SCHED_IORR``.
``MULTIBOOT2`` (a child node of ``FEATURES``):
Specify whether the ACRN hypervisor image can be booted using the
multiboot2 protocol. If not set, GRUB's multiboot2 is not available as a
boot option.
``RDT_ENABLED`` (a child node of ``FEATURES/RDT``):
Specify whether to enable the Resource Director Technology (RDT)
allocation feature. Set to 'y' to enable the feature or 'n' to disable it.
The 'y' will be ignored when hardware does not support RDT.
``CDP_ENABLED`` (a child node of ``FEATURES/RDT``):
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.
``CLOS_MASK`` (a child node of ``FEATURES/RDT``):
Specify the cache capacity bitmask for the CLOS; only continuous '1' bits
are allowed. The value will be ignored when hardware does not support RDT.
``HYPERV_ENABLED`` (a child node of ``FEATURES``):
Specify whether Hyper-V is enabled.
``IOMMU_ENFORCE_SNP`` (a child node of ``FEATURES``):
Specify whether IOMMU enforces snoop behavior of the DMA operation.
``ACPI_PARSE_ENABLED`` (a child node of ``FEATURES``):
Specify whether ACPI runtime parsing is enabled.
``L1D_VMENTRY_ENABLED`` (a child node of ``FEATURES``):
Specify whether the L1 cache flush before VM entry is enabled.
``MCE_ON_PSC_DISABLED`` (a child node of ``FEATURE``):
Specify whether force to disable software workaround for Machine Check
Error on Page Size Change is enabled.
``IVSHMEM`` (a child node of ``FEATURE``):
Specify the inter-VM shared memory configuration
``IVSHMEM_ENABLED`` (a child node of ``FEATURE/IVSHMEM``):
Specify if the inter-VM shared memory feature is enabled.
``IVSHMEM_REGION`` (a child node of ``FEATURE/IVSHMEM``):
Specify a comma-separated list of the inter-VM shared memory region name,
size, and VM IDs that may communicate using this shared region.
* Prefix the region ``name`` with ``hv:/`` (for an hv-land solution).
(See :ref:`ivshmem-hld` for details.)
* Specify the region ``size`` in MB, and a power of 2 (e.g., 2, 4, 8, 16)
up to 512.
* Specify all VM IDs that may use this shared memory area,
separated by a ``:``, for example, ``0:2`` (to share this area between
VMs 0 and 2), or ``0:1:2`` (to let VMs 0, 1, and 2 share this area).
``STACK_SIZE`` (a child node of ``MEMORY``):
Specify the size of stacks used by physical cores. Each core uses one stack
for normal operations and another three for specific exceptions.
``HV_RAM_SIZE`` (a child node of ``MEMORY``):
Specify the size of the RAM region used by the hypervisor.
``LOW_RAM_SIZE`` (a child node of ``MEMORY``):
Specify the size of the RAM region below address 0x10000, starting from address 0x0.
``SOS_RAM_SIZE`` (a child node of ``MEMORY``):
Specify the size of the Service OS VM RAM region.
``UOS_RAM_SIZE`` (a child node of ``MEMORY``):
Specify the size of the User OS VM RAM region.
``PLATFORM_RAM_SIZE`` (a child node of ``MEMORY``):
Specify the size of the physical platform RAM region.
``IOMMU_BUS_NUM`` (a child node of ``CAPACITIES``):
Specify the highest PCI bus ID used during IOMMU initialization.
``MAX_IR_ENTRIES`` (a child node of ``CAPACITIES``):
Specify the maximum number of Interrupt Remapping Entries.
``MAX_IOAPIC_NUM`` (a child node of ``CAPACITIES``):
Specify the maximum number of IOAPICs.
``MAX_PCI_DEV_NUM`` (a child node of ``CAPACITIES``):
Specify the maximum number of PCI devices.
``MAX_IOAPIC_LINES`` (a child node of ``CAPACITIES``):
Specify the maximum number of interrupt lines per IOAPIC.
``MAX_PT_IRQ_ENTRIES`` (a child node of ``CAPACITIES``):
Specify the maximum number of interrupt sources for PT devices.
``MAX_MSIX_TABLE_NUM`` (a child node of ``CAPACITIES``):
Specify the maximum number of MSI-X tables per device.
``MAX_EMULATED_MMIO`` (a child node of ``CAPACITIES``):
Specify the maximum number of emulated MMIO regions.
``GPU_SBDF`` (a child node of ``MISC_CFG``):
Specify the Segment, Bus, Device, and function of the GPU.
``vm``:
Specify the VM with VMID by its ``id`` attribute.
``vm_type``:
Current supported VM types are:
- ``SAFETY_VM`` pre-launched Safety VM
- ``PRE_STD_VM`` pre-launched Standard VM
- ``SOS_VM`` pre-launched Service VM
- ``POST_STD_VM`` post-launched Standard VM
- ``POST_RT_VM`` post-launched real-time capable VM
- ``KATA_VM`` post-launched Kata Container VM
``name`` (a child node of ``vm``):
Specify the VM name shown in the hypervisor console command: vm_list.
``guest_flags``:
Select all applicable flags for the VM:
- ``GUEST_FLAG_SECURE_WORLD_ENABLED`` specify whether 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
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)
``cpu_affinity``:
List of pCPU: the guest VM is allowed to create vCPU from all or a subset of this list.
``base`` (a child node of ``epc_section``):
SGX Enclave Page Cache section base; must be page aligned.
``size`` (a child node of ``epc_section``):
SGX Enclave Page Cache section size in bytes; must be page aligned.
``clos``:
Class of Service for Cache Allocation Technology settings. Refer to :ref:`hv_rdt` for details.
``start_hpa`` (a child node of ``memory``):
The start physical address in host for the VM.
``size`` (a child node of ``memory``):
The memory size in bytes for the VM.
``name`` (a child node of ``os_config``):
Specify the OS name of VM; currently, it is not referenced by the hypervisor code.
``kern_type`` (a child node of ``os_config``):
Specify the kernel image type so that the hypervisor can load it correctly.
Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.
``kern_mod`` (a child node of ``os_config``):
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`` (a child node of ``os_config``):
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`` (a child node of ``os_config``):
For internal use only and is not configurable. Specify the kernel boot arguments
in ``bootargs`` under the parent of ``board_private``.
``kern_load_addr`` (a child node of ``os_config``):
The loading address in host memory for the VM kernel.
``kern_entry_addr`` (a child node of ``os_config``):
The entry address in host memory for the VM kernel.
``legacy_vuart``:
Specify the vUART (aka COM) with the vUART ID by its ``id`` attribute.
Refer to :ref:`vuart_config` for detailed vUART settings.
``console_vuart``:
Specify the console vUART (aka PCI based vUART) with the vUART ID by
its ``id`` attribute.
Refer to :ref:`vuart_config` for detailed vUART settings.
``communication_vuart``:
Specify the communication vUART (aka PCI based vUART) with the vUART ID by
its ``id`` attribute.
Refer to :ref:`vuart_config` for detailed vUART settings.
``type`` (a child node of ``legacy_vuart``):
vUART (aka COM) type; currently only supports the legacy PIO mode.
``base`` (a child node of ``legacy_vuart``, ``console_vuart``, and ``communication_vuart``):
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.
console and communication vUART (A.K.A PCI based vUART) enabling switch.
Enable by specifying PCI_VUART; disable by returning INVALID_PCI_BASE.
``irq`` (a child node of ``legacy_vuart``):
vCOM IRQ.
``target_vm_id`` (a child node of ``legacy_vuart1``, ``communication_vuart``):
COM2 is used for VM communications. When it is enabled, specify which
target VM the current VM connects to.
``communication_vuart`` is used for VM communications. When it is enabled, specify
which target VM the current VM connects to.
``target_uart_id`` (a child node of ``legacy_vuart1`` and ``communication_vuart``):
Target vUART ID to which the vCOM2 connects.
Target vUART ID to which the ``communication_vuart`` connects.
``pci_dev_num``:
PCI devices number of the VM; it is hard-coded for each scenario so it
is not configurable for now.
``pci_devs``:
PCI devices list of the VM; it is hard-coded for each scenario so it
is not configurable for now.
``mmio_resources``:
MMIO resources to passthrough.
``TPM2`` (a child node of ``mmio_resources``):
TPM2 device to passthrough.
``p2sb`` (a child node of ``mmio_resources``):
Exposing the P2SB (Primary-to-Sideband) bridge to the pre-launched VM.
``pt_intx``:
Forward specific IOAPIC interrupts (with interrupt line remapping) to the pre-launched VM.
``board_private``:
Stores scenario-relevant board configuration.
``rootfs`` (a child node of ``board_private``):
rootfs for the Linux kernel.
``bootargs`` (a child node of ``board_private``):
Specify kernel boot arguments.
Launch XML format Launch XML format
================= =================

4
doc/tutorials/docbuild.rst
View File

@ -48,7 +48,7 @@ You'll need ``git`` installed to get the working folders set up:
.. code-block:: bash .. code-block:: bash
sudo apt-get install git sudo apt install git
We use the source header files to generate API documentation and we use We use the source header files to generate API documentation and we use
``github.io`` for publishing the generated documentation. Here's the ``github.io`` for publishing the generated documentation. Here's the
@ -137,7 +137,7 @@ For Ubuntu use:
.. code-block:: bash .. code-block:: bash
sudo apt-get install doxygen python3-pip \ sudo apt install doxygen python3-pip \
python3-wheel make graphviz xsltproc python3-wheel make graphviz xsltproc
Then use ``pip3`` to install the remaining Python-based tools: Then use ``pip3`` to install the remaining Python-based tools: