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).