Scenario Configuration Options¶

As explained in Introduction to ACRN Configuration, ACRN scenarios define the hypervisor (hv) and VM settings for the execution environment of an ACRN-based application. This document describes these option settings.

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.

hv ¶

The hypervisor configuration defines a working scenario and target board by configuring the hypervisor image features and capabilities such as setting up the log and the serial port.

hv.DEBUG_OPTIONS ¶

hv.DEBUG_OPTIONS.RELEASE¶

Build an image for release (y) or debug (n). In a release image, assertions are not enforced and debugging features are disabled, including logs, serial console, and the hypervisor shell. (Default value is n)
A Boolean value, written as y or n.

hv.DEBUG_OPTIONS.SERIAL_CONSOLE¶

Specify the host serial device used for hypervisor debugging. This option is only valid if hv.DEBUG_OPTIONS.RELEASE is set to n. This option impacts the content of vm.(legacy_vuart id="0").base when vm.vm_type is SERVICE_VM, which specifies the PIO base for Service VM legacy vUART 0 (used for the console). The PIO base for the Service VM’s legacy vUART 0 is determined using these rules:
- If hv.DEBUG_OPTIONS.SERIAL_CONSOLE is any available ttyS# in the native environment, the PIO base of the Service VM legacy vUART 0 would be the same as the PIO base corresponding to hv.DEBUG_OPTIONS.SERIAL_CONSOLE in the native environment.
- Otherwise, a PIO base would be assigned to the Service VM legacy vUART 0 from the available PIO list.
This logic is implemented in the configuration tools. (Default value is /dev/ttyS0)
Either empty or a string, such as /dev/ttyS0.

hv.DEBUG_OPTIONS.MEM_LOGLEVEL¶

Default loglevel for log messages stored in memory. Value can be changed at runtime. (Default value is 5)
An Integer from 0 to 7 representing log message severity and intent:
- 1 (LOG_FATAL) system is unusable
- 2 (LOG_ACRN) hypervisor failure
- 3 (LOG_ERROR) error conditions
- 4 (LOG_WARNING) warning conditions
- 5 (LOG_INFO) informational
- 6 (LOG_DEBUG) debug-level messages
A lower value has a higher severity. Log messages with a higher value (lower severity) are discarded.

hv.DEBUG_OPTIONS.NPK_LOGLEVEL¶

Default loglevel for the hypervisor North Peak (NPK) log. Value can be changed at runtime. (Default value is 5)
An Integer from 0 to 7 representing log message severity and intent:
- 1 (LOG_FATAL) system is unusable
- 2 (LOG_ACRN) hypervisor failure
- 3 (LOG_ERROR) error conditions
- 4 (LOG_WARNING) warning conditions
- 5 (LOG_INFO) informational
- 6 (LOG_DEBUG) debug-level messages
A lower value has a higher severity. Log messages with a higher value (lower severity) are discarded.

hv.DEBUG_OPTIONS.CONSOLE_LOGLEVEL¶

Default loglevel for log messages written to the serial console. (Default value is 3)
An Integer from 0 to 7 representing log message severity and intent:
- 1 (LOG_FATAL) system is unusable
- 2 (LOG_ACRN) hypervisor failure
- 3 (LOG_ERROR) error conditions
- 4 (LOG_WARNING) warning conditions
- 5 (LOG_INFO) informational
- 6 (LOG_DEBUG) debug-level messages
A lower value has a higher severity. Log messages with a higher value (lower severity) are discarded.

hv.DEBUG_OPTIONS.LOG_DESTINATION¶

Bitmap indicating the destination of log messages. There are three log destinations available:
- 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 hv.DEBUG_OPTIONS.RELEASE is n). (Default value is 7)
Integer value from 0 to 7.

hv.DEBUG_OPTIONS.LOG_BUF_SIZE¶

Capacity (in bytes) of logbuf for each physical CPU, for example, 0x40000. (Default value is 0x40000)
An Integer value in hexadecimal format.

hv.FEATURES ¶

hv.FEATURES.RELOC¶

Specify if hypervisor relocation is enabled on booting. (Default value is y)
A Boolean value, written as y or n.

hv.FEATURES.SCHEDULER¶

The CPU scheduler used by the hypervisor. (Default value is SCHED_BVT)
Four scheduler options are supported:
- SCHED_NOOP: The NOOP (No-Operation) scheduler means there is a strict 1 to 1 mapping between vCPUs and pCPUs.
- SCHED_IORR: The IORR (IO sensitive Round Robin) scheduler supports multiple vCPUs running on one pCPU, scheduled by a IO sensitive round robin policy.
- SCHED_BVT: The BVT (Borrowed Virtual Time) scheduler is a virtual time based scheduling algorithm, it dispatches the runnable thread with the earliest effective virtual time. TODO: BVT scheduler will be built on top of a prioritized scheduling mechanism, i.e. higher priority threads get scheduled first, and same priority tasks are scheduled per BVT.
- SCHED_PRIO: The priority based scheduler. vCPU scheduling will be based on their pre-configured priorities.
Read more about the available scheduling options in Enable CPU Sharing in ACRN.

hv.FEATURES.MULTIBOOT2¶

Specify if the ACRN hypervisor image can be booted using the multiboot2 protocol. If set to n, GRUB’s multiboot2 is not available as a boot option. (Default value is y)
A Boolean value, written as y or n.

hv.FEATURES.ENFORCE_TURNOFF_AC¶

Force to disable #AC for Split-locked Access. If CPU has #AC for split-locked access, HV enables it and VMs can’t disable. Set this to enforce turning off that #AC, for debugging purposes only. (Default value is y)
A Boolean value, written as y or n.

hv.FEATURES.ENFORCE_TURNOFF_GP¶

Force to disable #GP for Split-locked Access. If CPU has #GP for UC lock, HV enable it and VMs can’t disable. Set this to enforce turn off that #GP, for community developer only. (Default value is n)
A Boolean value, written as y or n.

hv.FEATURES.SECURITY_VM_FIXUP¶

Enable to do fixup for TPM2 and SMBIOS for Security VM. If no Security VM, setting this option to n (Default value is n)
A Boolean value, written as y or n.

hv.FEATURES.RDT¶

Enable the Intel Resource Director Technology (RDT) allocation feature and Code and Data Prioritization (CDP). If the board hardware does not support RDT or CDP, setting this option to y is ignored.

hv.FEATURES.RDT.RDT_ENABLED¶

Enable the Intel Resource Director Technology (RDT) allocation feature. If the board hardware does not support RDT, setting this option to y is ignored. (Default value is n)
A Boolean value, written as y or n.

hv.FEATURES.RDT.CDP_ENABLED¶

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. (Default value is n)
A Boolean value, written as y or n.

hv.FEATURES.RDT.VCAT_ENABLED¶

Specify whether to enable CAT virtualization (vCAT). Set to ‘y’ to enable the feature or ‘n’ to disable it. The ‘y’ will be ignored when hardware does not support CAT. (Default value is n)
A Boolean value, written as y or n.

hv.FEATURES.RDT.CLOS_MASK¶

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. This option takes effect only if hv.FEATURES.RDT.RDT_ENABLED is set to y. As vm.clos.vcpu_clos specifies the index of the CLOS to be associated with the given vCPU, hv.FEATURES.RDT.CLOS_MASK of that CLOS would impact the performance of the given vCPU. (Optional)
String

hv.FEATURES.RDT.MBA_DELAY¶

Memory Bandwidth Allocation delay value. (Optional)
String

hv.FEATURES.HYPERV_ENABLED¶

Enable Hyper-V. (Default value is y)
A Boolean value, written as y or n.

hv.FEATURES.NVMX_ENABLED¶

Enable nested virtualization. (Default value is n)
A Boolean value, written as y or n.

hv.FEATURES.IOMMU_ENFORCE_SNP¶

Specify if the IOMMU enforces snoop behavior of DMA operations. (Default value is n)
A Boolean value, written as y or n.

hv.FEATURES.ACPI_PARSE_ENABLED¶

Enable ACPI runtime parsing. (Default value is y)
A Boolean value, written as y or n.

hv.FEATURES.L1D_VMENTRY_ENABLED¶

Enable L1 cache flush before VM entry. Default value n. (Default value is n)
A Boolean value, written as y or n.

hv.FEATURES.MCE_ON_PSC_DISABLED¶

Force disabling software workaround for Machine Check Error on Page Size Change. (Default value is n)
A Boolean value, written as y or n.

hv.FEATURES.IVSHMEM¶

Enable Inter-VM Shared memory feature.

hv.FEATURES.IVSHMEM.IVSHMEM_ENABLED¶

Enable inter-VM shared memory (IVSHMEM) feature. (Default value is n)
A Boolean value, written as y or n.

hv.FEATURES.IVSHMEM.IVSHMEM_REGION¶

A comma-separated list with 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 ACRN Shared Memory Based Inter-VM Communication for details.)
- Specify the region size in MB. Must be 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, use 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).
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 Ivshmem HV-Land Usage for more information.

hv.FEATURES.SSRAM¶

Pseudo SRAM configuration. (Optional)

hv.FEATURES.SSRAM.SSRAM_ENABLED¶

Enable PTCM (Platform Tuning Configuration Manager). (Default value is n)
A Boolean value, written as y or n.

hv.MEMORY ¶

hv.MEMORY.STACK_SIZE¶

Capacity of one stack (in bytes) used by a physical core. Each core uses one stack for normal operation and another three for specific exceptions. (Default value is 0x2000)
An Integer value in hexadecimal format.

hv.MEMORY.HV_RAM_START¶

The 2MB-aligned starting physical address of the RAM region used by the hypervisor. (Default value is 0x00400000)
An Integer value in hexadecimal format.

hv.MEMORY.LOW_RAM_SIZE¶

Size of the low RAM region below address 0x10000, starting from address 0x0. (Default value is 0x00010000)
An Integer value in hexadecimal format.

hv.MEMORY.PLATFORM_RAM_SIZE¶

Size of the physical platform RAM. Default value 0x400000000. (Default value is 0x400000000)
An Integer value in hexadecimal format.

hv.CAPACITIES ¶

hv.CAPACITIES.MAX_VM_NUM¶

Maximum number of User VMs allowed. (Default value is 8)
Integer from 1 to 8.

hv.CAPACITIES.IOMMU_BUS_NUM¶

Highest PCI bus ID used during IOMMU initialization. (Default value is 0x100)
An Integer value in hexadecimal format.

hv.CAPACITIES.MAX_IR_ENTRIES¶

Maximum number of Interrupt Remapping Entries. (Default value is 256)
Integer

hv.CAPACITIES.MAX_IOAPIC_NUM¶

Maximum number of IOAPICs. (Default value is 1)
Integer from 1 to 10.

hv.CAPACITIES.MAX_PCI_DEV_NUM¶

Maximum number of PCI devices. (Default value is 96)
Integer from 1 to 1024.

hv.CAPACITIES.MAX_IOAPIC_LINES¶

Maximum number of interrupt lines per IOAPIC. (Default value is 120)
Integer from 1 to 120.

hv.CAPACITIES.MAX_PT_IRQ_ENTRIES¶

The pre-defined number of interrupt sources of all pass-through devices. (Default value is 256)
Integer

hv.CAPACITIES.MAX_MSIX_TABLE_NUM¶

Pre-defined maximum number of virtual MSI-X table entries per device. If this value is empty, then the default value will be calculated from information in the board XML file. (Default value is 64)
Integer value from 1 to 2048.

hv.CAPACITIES.MAX_EMULATED_MMIO¶

Maximum number of emulated MMIO regions. (Default value is 16)
Integer value from 1 to 128.

hv.MISC_CFG ¶

hv.MISC_CFG.GPU_SBDF¶

Segment, Bus, Device, and function of the GPU. (Default value is 0x00000010)
An Integer value in hexadecimal format.

hv.MISC_CFG.UEFI_OS_LOADER_NAME¶

UEFI OS loader name. (Optional)
String

vm ¶

VM configuration includes scenario-based VM configuration information that is used to describe the characteristics and attributes for all VMs in a user scenario. It also includes launch script-based VM configuration information, where parameters are passed to the device model to launch post-launched User VMs.

vm.vm_type ¶

vm.vm_type¶

Specify the VM type.
Current supported VM types are:
- SAFETY_VM pre-launched Safety VM
- PRE_STD_VM pre-launched Standard VM
- PRE_RT_VM pre-launched real-time capable VM
- SERVICE_VM pre-launched Service VM
- POST_STD_VM post-launched Standard VM
- POST_RT_VM post-launched real-time capable VM

vm.name ¶

vm.name¶

Specify the VM name shown in the hypervisor console vm_list command.
string from 1 to 32 characters long.

vm.guest_flags ¶

Select all applicable flags for the VM. (Optional)

vm.guest_flags.guest_flag¶

Select all applicable flags for the VM.
- 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 that LAPIC is passed through
- GUEST_FLAG_IO_COMPLETION_POLLING specify that the hypervisor needs IO polling to completion
- 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)
- GUEST_FLAG_NVMX_ENABLED specify that the VM supports nested virtualization
- GUEST_FLAG_SECURITY_VM specify that the VM needs to do security-vm related
- GUEST_FLAG_VCAT_ENABLED specify that the VM supports CAT virtualization fixup (TPM2 passthrough and SMBIOS passthrough)

vm.cpu_affinity ¶

List of pCPU that this VM’s vCPUs are pinned to. (Optional)

vm.cpu_affinity.pcpu_id¶

A pCPU that this VM’s vCPU is allowed to pin to. (Default value is 2)
Integer

vm.clos ¶

Class of Service for Cache Allocation Technology. Refer SDM 17.19.2 for details, and use with caution.

vm.clos.vcpu_clos¶

By default (GUEST_FLAG_VCAT_ENABLED is not specified): vcpu_clos is per-CPU and it configures each CPU in VMs to a desired CLOS ID in the VM section of the scenario file. Follow RDT Detection and Resource Capabilities to identify the maximum supported CLOS ID that can be used.

If GUEST_FLAG_VCAT_ENABLED is specified: vcpu_clos is not per-CPU anymore, just a list of physical CLOSIDs (minimum 2) that are assigned to VMs for vCAT use. Each vcpu_clos will be mapped to a virtual CLOSID, the first vcpu_clos is mapped to virtual CLOSID 0 and the second is mapped to virtual CLOSID 1, etc. (Default value is 0)
Integer

vm.epc_section ¶

Specify SGX Enclave Page Cache section base and size in byte. It must be page aligned. (Optional)

vm.epc_section.base¶

SGX EPC section base, must be page aligned. (Default value is 0)
An Integer value in hexadecimal format.

vm.epc_section.size¶

SGX EPC section size in Bytes, must be page aligned. (Default value is 0)
An Integer value in hexadecimal format.

vm.memory ¶

Specify memory information for Service and User VMs. (Optional)

vm.memory.start_hpa¶

The starting physical address in host for the VM. (Default value is 0x100000000)
An Integer value in hexadecimal format.

vm.memory.size¶

The memory size in bytes for the VM. Default value is 0x200000000. (Optional) (Default value is 0x20000000)
An Integer value in hexadecimal format.

vm.memory.start_hpa2¶

Start of second HPA for non-contiguous allocations in host for the VM. (Optional) (Default value is 0x0)
An Integer value in hexadecimal format.

vm.memory.size_hpa2¶

Memory size of second HPA for non-contiguous allocations in Bytes for the VM. (Optional) (Default value is 0x0)
An Integer value in hexadecimal format.

vm.priority ¶

vm.priority¶

Specify the VM vCPU priority for scheduling. (Default value is PRIO_LOW)
Two priorities are supported for priority based scheduler:
- PRIO_LOW: low priority for vCPU scheduling.
- PRIO_HIGH: high priority for vCPU scheduling.

vm.os_config ¶

General information for host kernel, boot argument and memory. (Optional)

vm.os_config.name¶

Specify the OS name of VM. Is not referenced by the hypervisor code.
A string with 1 to 32 characters.

vm.os_config.kern_type¶

Specify the kernel image type so the hypervisor can load it correctly.
A string with either KERNEL_BZIMAGE, KERNEL_ELF or KERNEL_RAWIMAGE.

vm.os_config.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.
String

vm.os_config.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.
String

vm.os_config.bootargs¶

Configurable boot argument for pre-launched VM of hybrid or hybrid_rt mode.
String

vm.os_config.kern_load_addr¶

The loading address in host memory for the VM kernel. (Optional)
Either empty, or an Integer value in hexadecimal format.

vm.os_config.kern_entry_addr¶

The entry address in host memory for the VM kernel. (Optional)
Either empty, or an Integer value in hexadecimal format.

vm.legacy_vuart ¶

Specify the vUART (aka COM) with the vUART ID by its id attribute. Refer to Enable vUART Configurations for detailed vUART settings.

vm.legacy_vuart.type¶

vUART (COM) type; only legacy PIO mode is supported. (Default value is VUART_LEGACY_PIO)
vCOM type

vm.legacy_vuart.base¶

vUART (COM) enabling switch. Enable by exposing its COM_BASE (e.b., SERVICE_VM_COM1_BASE for Service VM); disable by returning INVALID_COM_BASE.
A string with either SERVICE_VM_COM1_BASE, SERVICE_VM_COM2_BASE, SERVICE_VM_COM3_BASE, SERVICE_VM_COM4_BASE, COM1_BASE, COM2_BASE, COM3_BASE, COM4_BASE, CONFIG_COM_BASE, or indicating it’s disabled with INVALID_COM_BASE.

vm.legacy_vuart.irq¶

vCOM IRQ.
A string with either SERVICE_VM_COM1_IRQ, SERVICE_VM_COM2_IRQ, SERVICE_VM_COM3_IRQ, SERVICE_VM_COM4_IRQ, COM1_IRQ, COM2_IRQ, COM3_IRQ, COM4_IRQ, CONFIG_COM_IRQ or 0. If 0 is set, the vuart will use polling mode.

vm.legacy_vuart.target_vm_id¶

COM2 is used for VM communications. When it is enabled, specify which target VM the current VM connects to. (Optional) (Default value is 1)
Integer

vm.legacy_vuart.target_uart_id¶

Target vUART ID to which the vCOM2 connects. (Optional) (Default value is 1)
Integer

vm.console_vuart ¶

Specify the console vUART (aka PCI based vUART) with the vUART ID by its id attribute.

vm.console_vuart.base¶

Console vUART (A.K.A PCI based vUART) enabling switch. Enable by specifying PCI_VUART; disable by specifying INVALID_PCI_BASE. (Default value is INVALID_PCI_BASE)
A string with PCI_VUART or indicating its disabled using INVALID_PCI_BASE.

vm.communication_vuart ¶

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.

vm.communication_vuart.base¶

Communication vUART (A.K.A PCI based vUART) enabling switch. Enable by specifying PCI_VUART; disable by specifying INVALID_PCI_BASE. (Default value is INVALID_PCI_BASE)
A string with PCI_VUART or indicating its disabled using INVALID_PCI_BASE.

vm.communication_vuart.target_vm_id¶