diff --git a/doc/reference/config-options.rst b/doc/reference/config-options.rst
index 8a3433520..a8f637a2d 100644
--- a/doc/reference/config-options.rst
+++ b/doc/reference/config-options.rst
@@ -7,6 +7,8 @@ As explained in :ref:`acrn_configuration_tool`, ACRN scenarios define
the hypervisor (hv) and VM settings for the execution environment of an
ACRN-based application. This document describes these option settings.
+.. rst-class:: rst-columns3
+
.. contents::
:local:
:depth: 2
diff --git a/doc/scripts/configdoc.xsl b/doc/scripts/configdoc.xsl
index 2bf7e654c..d5757f23d 100644
--- a/doc/scripts/configdoc.xsl
+++ b/doc/scripts/configdoc.xsl
@@ -4,10 +4,10 @@
version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
+
-
-
+
+
@@ -50,28 +50,29 @@
-
-
-
+
+
+
-
+
-
+
+
-
+
-
-
+
+
@@ -81,66 +82,68 @@
-
+
-
+
-
-
+
-
+
-
-
-
+
+
- -
-
-
+
+
+
+
+
-
-
+
+
-
-
+
+
-
-
+
-
+
-
+
1
@@ -149,14 +152,14 @@
-
+
1
The **
-
+
** option is
@@ -170,35 +173,57 @@
-
+
occurrence
s
-
+
to
-
+
occurrences
.
-
+
-
+
+
+
+
+
+
+ *(Optional)*
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
+
+
-
+
@@ -208,69 +233,70 @@
-->
-
-
+
+
-
+
-
-
+
+
-
-
-
+
+
+
-
+
-
+
-
+
-
+
-
+
-
+
+
.. option::
-
-
+
+
-
-
+
+
-
-
+
+
-
+
-
+
-
-
+
+
-
+
diff --git a/doc/tutorials/enable_ivshmem.rst b/doc/tutorials/enable_ivshmem.rst
index 025ddb742..20e7723f9 100644
--- a/doc/tutorials/enable_ivshmem.rst
+++ b/doc/tutorials/enable_ivshmem.rst
@@ -33,6 +33,8 @@ where
.. note:: This device can be used with real-time VM (RTVM) as well.
+.. _ivshmem-hv:
+
ivshmem hv-land usage
*********************
diff --git a/misc/config_tools/schema/VMtypes.xsd b/misc/config_tools/schema/VMtypes.xsd
index f1e031972..cf2cb1f4f 100644
--- a/misc/config_tools/schema/VMtypes.xsd
+++ b/misc/config_tools/schema/VMtypes.xsd
@@ -29,14 +29,14 @@
-- 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)
+- ``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)
@@ -64,7 +64,8 @@
- A pCPU that this VM's vCPU is allowed to pin to.
+ A pCPU that this VM's vCPU is allowed to pin
+to.
@@ -76,7 +77,8 @@
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.
+to identify the maximum supported CLOS ID that can be used. Default
+value ``0``.
@@ -94,7 +96,8 @@ to identify the maximum supported CLOS ID that can be used.
- SGX EPC section size in Bytes, must be page aligned.
+ SGX EPC section size in Bytes, must be page
+aligned.
@@ -104,22 +107,26 @@ to identify the maximum supported CLOS ID that can be used.
- The start physical address in host for the VM.
+ The starting physical address in host for the
+VM.
- The memory size in bytes for the VM.
+ The memory size in bytes for the VM. Default
+value is ``0x200000000``.
- Start of second HPA for non-contiguous allocations in host for the VM.
+ Start of second HPA for non-contiguous
+allocations in host for the VM.
- Memory size of second HPA for non-contiguous allocations in Bytes for the VM.
+ Memory size of second HPA for non-contiguous
+allocations in Bytes for the VM.
@@ -128,10 +135,13 @@ to identify the maximum supported CLOS ID that can be used.
-
- Specify the OS name of VM; currently, it is not referenced by the hypervisor code.String from 1 to 32
-characters long.
+ Specify the OS name of VM.
+Is not referenced by the hypervisor code.
+
+
+
+ A string with 1 to 32 characters.
@@ -141,8 +151,7 @@ characters long.
- Specify the kernel image type so that the hypervisor can load it correctly.
-Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.
+ Specify the kernel image type so the hypervisor can load it correctly.
@@ -177,8 +186,8 @@ must exactly match the module tag in the GRUB multiboot cmdline.
- Specify the kernel image type so that the hypervisor can load it correctly.
-Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.
+ A string with either ``KERNEL_BZIMAGE`` or
+``KERNEL_ZEPHYR``.
@@ -198,7 +207,9 @@ Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.
- vUART (A.K.A COM) enabling switch. Enable by exposing its base address, disable by returning INVALID_COM_BASE.
+ 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``.
@@ -213,7 +224,9 @@ Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.
- vCOM irq
+ 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``.
@@ -230,17 +243,19 @@ Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``.
-
+
- vUART (aka COM) type; currently only supports the legacy PIO mode.
+ vUART (COM) type; only legacy PIO mode is
+supported.
- 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.
+ vUART (COM) enabling switch. Enable by exposing its COM_BASE
+(e.b., ``SOS_COM1_BASE`` for Service VM); disable by returning
+``INVALID_COM_BASE``.
@@ -265,8 +280,8 @@ target VM the current VM connects to.
- PCI based vUART enabling switch. Enable by specifying PCI_VUART;
-disable by returning INVALID_PCI_BASE.
+ A string with ``PCI_VUART`` or indicating its
+disabled using ``INVALID_PCI_BASE``.
@@ -279,7 +294,8 @@ disable by returning INVALID_PCI_BASE.
Console vUART (A.K.A PCI based vUART) enabling switch.
- Enable by specifying PCI_VUART; disable by returning INVALID_PCI_BASE.
+Enable by specifying PCI_VUART; disable by specifying
+``INVALID_PCI_BASE``.
@@ -291,7 +307,8 @@ disable by returning INVALID_PCI_BASE.
Communication vUART (A.K.A PCI based vUART) enabling switch.
-Enable by specifying PCI_VUART; disable by returning INVALID_PCI_BASE.
+Enable by specifying PCI_VUART; disable by specifying
+``INVALID_PCI_BASE``.
@@ -312,12 +329,13 @@ Enable by specifying PCI_VUART; disable by returning INVALID_PCI_BASE.
- TPM2 device to passthrough.
+ Specify TPM2 device to passthrough.
- Exposing the P2SB (Primary-to-Sideband) bridge to the pre-launched VM.
+ Expose the P2SB (Primary-to-Sideband) bridge
+to the pre-launched VM.
diff --git a/misc/config_tools/schema/config.xsd b/misc/config_tools/schema/config.xsd
index bfb136007..01b0a2c26 100644
--- a/misc/config_tools/schema/config.xsd
+++ b/misc/config_tools/schema/config.xsd
@@ -16,54 +16,55 @@
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
+In a **release** image, assertions are not enforced and debugging
+features are disabled, including logs, serial console, and the
+hypervisor shell.
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.
+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.
- Default loglevel for log messages stored in memory.
-Messages with a lower severity (higher value) are discarded.
+ Default loglevel for log messages stored in
+memory. Value can be changed at runtime.
- Default loglevel for the hypervisor NPK log.
+ Default loglevel for the hypervisor North Peak
+(NPK) log. Value can be changed at runtime.
Default loglevel for log messages
-written to the serial console. Messages with lower severity (higher
-value) are not displayed.
+written to the serial console.
-
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``).
+
+
+ integer value from 0 to 7.
+
@@ -81,13 +82,14 @@ physical cpu, for example, ``0x40000``.
- Options for hypervisor feature enablement.
+ Options for enabling hypervisor features.
- Specify if hypervisor relocation is enabled on booting.
+ Specify if hypervisor relocation is enabled on
+booting.
@@ -127,7 +129,8 @@ of DMA operations.
- Enable L1 cache flush before VM entry.
+ Enable L1 cache flush before VM entry. Default
+value ``n``.
@@ -172,22 +175,25 @@ the RAM region used by the hypervisor.
Size of the low RAM region below address
-``0x10000``, starting from address ``0x0``..
+``0x10000``, starting from address ``0x0``.
- Size of the User VM OS RAM region.
+ Size of the User VM OS RAM region. Default
+value ``0x200000000``.
- Size of the Service VM OS RAM region.
+ Size of the Service VM OS RAM region. Default
+value ``0x400000000``.
- Size of the physical platform RAM.
+ Size of the physical platform RAM. Default
+value ``0x400000000``.
@@ -201,7 +207,8 @@ maximum supported resource.
- Highest PCI bus ID used during IOMMU initialization.
+ Highest PCI bus ID used during IOMMU
+initialization.
@@ -210,10 +217,13 @@ maximum supported resource.
+
+ Maximum number of IOAPICs.
+
-
- Maximum number of IO-APICs. Integer from 1 to 10.
-
+
+ integer from 1 to 10.
+
@@ -222,14 +232,17 @@ maximum supported resource.
- >Maximum number of KATA VM.
+ Maximum number of KATA VM.
+
+ Maximum number of PCI devices.
+
-
- Maximum number of PCI devices.Integer from 1 to 1024.
-
+
+ integer from 1 to 1024.
+
@@ -237,10 +250,13 @@ maximum supported resource.
+
+ Maximum number of interrupt lines per IOAPIC.
+
-
- Maximum number of interrupt lines per IOAPIC.Integer from 1 to 120.
-
+
+ integer from 1 to 120.
+
@@ -249,14 +265,17 @@ maximum supported resource.
- Maximum number of interrupt source for PT devices.
+ Maximum number of interrupt source for PT
+devices.
+
+ Maximum number of MSI-X tables per device.
+
- Maximum number of MSI-X tables per device.
-Leave blank if not sure.Integer from 1 to 2048.
+ integer value from 1 to 2048.
@@ -265,9 +284,12 @@ Leave blank if not sure.Integer from 1 to 2048.
+
+ Maximum number of emulated MMIO regions.
+
- Maximum number of emulated MMIO regions.Integer from 1 to 128.
+ integer value from 1 to 128.
@@ -311,11 +333,13 @@ Leave blank if not sure.Integer from 1 to 2048.
-
Specify the VM name shown in the
- hypervisor console ``vm_lists`` command. String from 1 to 32
- characters long.
+hypervisor console ``vm_lists`` command.
+
+
+
+ string from 1 to 32 characters long.
@@ -346,35 +370,16 @@ Refer SDM 17.19.2 for details, and use with caution.
- 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.
+ Specify memory information for Service and User VMs.
- 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.
+ General information for host kernel, boot
+argument and memory.
-
+
Specify the vUART (aka COM) with the vUART ID by its ``id`` attribute.
Refer to :ref:`vuart_config` for detailed vUART settings.
@@ -389,7 +394,7 @@ its ``id`` attribute.
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.
+its ``id`` attribute. When it is enabled, specify which target VM's vUART the current VM connects to.
@@ -409,7 +414,7 @@ its ``id`` attribute. When it is enabled, specify which target VM's vuart the cu
- pci devices list.
+ PCI devices list.
diff --git a/misc/config_tools/schema/types.xsd b/misc/config_tools/schema/types.xsd
index 897d03970..ee2b7cc3d 100644
--- a/misc/config_tools/schema/types.xsd
+++ b/misc/config_tools/schema/types.xsd
@@ -28,21 +28,21 @@
- Either empty, or a hexadecimal value.
+ Either empty, or an integer value in hexadecimal format.
- Either empty, or a hexadecimal value.
+ Either empty, or an integer value in hexadecimal format.
- Integer from 1 to 2048.
+ integer from 1 to 2048.
@@ -65,8 +65,7 @@
- Either a hexadecimal value or the string
-``CONFIG_SOS_RAM_SIZE``.
+ An integer value in hexadecimal format.
@@ -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.
+A lower value has a higher severity. Log messages with a
+higher value (lower severity) are discarded.
@@ -125,7 +123,7 @@ Read more about the available scheduling options in :ref:`cpu_sharing`.
- Either empty or a string.
+ Either empty or a string, such as ``/dev/ttyS0``.
@@ -138,7 +136,9 @@ Read more about the available scheduling options in :ref:`cpu_sharing`.
- Either empty or a string.
+ 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.
@@ -148,7 +148,8 @@ Read more about the available scheduling options in :ref:`cpu_sharing`.
- Enable inter-VM shared memory (IVSHMEM) feature.
+ Enable inter-VM shared memory (IVSHMEM)
+feature.
@@ -181,7 +182,8 @@ RDT, setting this option to ``y`` is ignored.
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.
+The 'y' will be ignored when hardware does not support CDP. Default
+value ``n``.
@@ -202,7 +204,8 @@ are allowed. The value will be ignored when hardware does not support RDT.
- Enable PTCM (Platform Tuning Configuration Manager).
+ Enable PTCM (Platform Tuning Configuration
+Manager).