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 displayed as a check box, checked indicating true.
- Hexadecimal
A base-16 (integer) value represented by a leading
0x
or0X
followed by one or more characters0
to9
,a
tof
, orA
toF
.- Integer
A base-10 value represented by the characters
0
to9
. The first character must not be a0
. 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.
We use icons within an option description to indicate where the option can be found within the Configurator UI:
Hypervisor/VM Tab |
Basic/Advanced Tab |
---|---|
|
|
|
|
|
|
|
Hypervisor Options¶
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.
Hypervisor features¶
Enable hypervisor features.
- Hypervisor relocation¶
/
Enable hypervisor relocation in memory. The bootloader may need to change the location of the hypervisor because of other firmware. (Default value is
y
)A Boolean value, displayed as a check box.
- Virtual CPU scheduler¶
/
Select the scheduling algorithm for determining the priority of User VMs running on a shared virtual CPU. (Default value is
SCHED_BVT
)A string specifying the scheduling option:
No-Operation (NOOP)
: The No-Operation (NOOP) scheduler means there is a strict one-to-one mapping between vCPUs and pCPUs.Borrowed Virtual Time
: The Borrowed Virtual Time (BVT) scheduler is a virtual time-based scheduling algorithm. It dispatches the runnable thread with the earliest effective virtual time.Priority Based Scheduling
: The priority based scheduler supports vCPU scheduling based on pre-configured priorities.
Read more about the available scheduling options in Enable CPU Sharing in ACRN.
- Multiboot2¶
/
Enable multiboot2 protocol support (with multiboot1 downward compatibility). If multiboot1 meets your requirements, disable this feature to reduce hypervisor code size. (Default value is
y
)A Boolean value, displayed as a check box.
- Split lock detection¶
/
Enable detection of split locks. A split lock can negatively affect an application’s real-time performance. If a lock is detected, an alignment check exception #AC occurs. (Default value is
y
)A Boolean value, displayed as a check box.
- UC lock detection¶
/
Enable detection of uncacheable-memory (UC) locks. A UC lock can negatively affect an application’s real-time performance. If a lock is detected, a general-protection exception #GP occurs. (Default value is
n
)A Boolean value, displayed as a check box.
- Hyper-V¶
/
Enable Microsoft Hyper-V Hypervisor Top-Level Functional Specification (TFLS) for User VMs running Windows. (Default value is
y
)A Boolean value, displayed as a check box.
- Parse ACPI tables¶
/
Enable ACPI runtime parsing to get DMAR (DMA remapping) configuration data from the APCI tables. Otherwise, use existing, static information from the associated board configuration file. (Default value is
y
)A Boolean value, displayed as a check box.
- Mitigate L1 terminal fault¶
/
Enable L1 cache flush before VM entry to prevent L1 terminal fault. L1 terminal fault is a hardware vulnerability that could allow unauthorized disclosure of information residing in the L1 data cache. (Default value is
y
)A Boolean value, displayed as a check box.
- MCE workaround¶
/
Enable the software workaround for Machine Check Error on Page Size Change (erratum in some processor families). (Default value is
y
)A Boolean value, displayed as a check box.
Intel Resource Director Tech¶
Intel Resource Director Technology (RDT) provides cache and memory bandwidth allocation features. The features can be used to improve an application’s real-time performance.
- Intel Resource Director Tech¶
/
Enable Intel Resource Director Technology (RDT). If the board hardware does not support RDT, setting this option to checked is ignored. (Default value is
n
)A Boolean value, displayed as a check box.
- Code and Data Prioritization¶
/
Enable Code and Data Prioritization (CDP). CDP provides control over code and data placement in cache to improve an application’s real-time performance. (Default value is
n
)A Boolean value, displayed as a check box.
- Virtual Cache Allocation Tech¶
/
Enable virtualization of the Cache Allocation Technology (CAT) feature in RDT. CAT enables you to allocate cache to VMs, providing isolation to avoid performance interference from other VMs. (Default value is
n
)A Boolean value, displayed as a check box.
Software SRAM¶
Configure Software SRAM. This feature reserves memory buffers as always-cached memory to improve an application’s real-time performance.
- Software SRAM¶
/
Enable Software SRAM. This feature reserves memory buffers as always-cached memory to improve an application’s real-time performance. (Default value is
n
)A Boolean value, displayed as a check box.
Debug options¶
Configure the debug facilities.
- Build type¶
/
Select the build type:
Debug
enables the debug shell, prints, and logs.Release
optimizes the ACRN binary for deployment and turns off all debug infrastructure.
These settings can only be changed at build time. (Default value is
debug
)A string with value
Release
orDebug
that indicates the build type of the hypervisor.
- Serial console port¶
/
Select the host serial device used for hypervisor debugging. (Default value is
None
)String value
- ACRN log level¶
/
Select the default log level for log messages stored in memory. Value can be changed at runtime. Log messages with the selected value or lower are displayed. (Default value is
0
)An Integer from 0 to 5 representing log message severity and intent:
0: None
: No log at all.1: Critical
: Messages about critical errors that cause the hypervisor to crash or hang (almost) immediately.2: Error
: Messages about significant errors that affect the main functions (for example, launch of VMs) of ACRN hypervisor.3: Warning
: Messages about detected abnormalities that have local effects on certain features.4: Information
: Informational messages5: Debug
: Debug-level messages
A lower value has a higher severity. Log messages with a higher value (lower severity) are discarded.
- Intel Trace Hub log level¶
/
Select the default log level for the hypervisor via Intel Trace Hub log. Use the Intel Trace Hub’s memory to record log messages. Value can be changed at runtime. Log messages with the selected value or lower are displayed. (Default value is
0
)An Integer from 0 to 5 representing log message severity and intent:
0: None
: No log at all.1: Critical
: Messages about critical errors that cause the hypervisor to crash or hang (almost) immediately.2: Error
: Messages about significant errors that affect the main functions (for example, launch of VMs) of ACRN hypervisor.3: Warning
: Messages about detected abnormalities that have local effects on certain features.4: Information
: Informational messages5: Debug
: Debug-level messages
A lower value has a higher severity. Log messages with a higher value (lower severity) are discarded.
- Serial console log level¶
/
Select the default log level for log messages written to the serial console. Log messages with the selected value or lower are displayed. (Default value is
0
)An Integer from 0 to 5 representing log message severity and intent:
0: None
: No log at all.1: Critical
: Messages about critical errors that cause the hypervisor to crash or hang (almost) immediately.2: Error
: Messages about significant errors that affect the main functions (for example, launch of VMs) of ACRN hypervisor.3: Warning
: Messages about detected abnormalities that have local effects on certain features.4: Information
: Informational messages5: Debug
: Debug-level messages
A lower value has a higher severity. Log messages with a higher value (lower severity) are discarded.
Inter-VM virtual UART connection¶
Specify the vUART connection settings. Refer to Enable vUART Configurations for detailed vUART settings.
vuart_connection¶
- vUART name¶
/
Specify the vUART name.
String value
- vUART Type¶
/
Select the communication virtual UART (vUART) type. (Default value is
legacy
)A string with value:
legacy
orpci
.
- Virtual UART port¶
/
Virtual UART port
String value
- Virtual I/O address¶
/
Specify the COM base for each legacy virtual UART. (Default value is
0x3F
)An Integer value in hexadecimal format (with a leading
0x
).
- Virtual UART BDF¶
/
Specify the virtual Bus:Device.Function (BDF) for each PCI virtual UART. Virtual BDF is automatically assigned when the configuration is saved and can be changed if needed.
A string with up to two hex digits, a
:
, two hex digits, a.
, and one digit between 0-7.
Memory options¶
Configure memory used by the hypervisor.
- CPU memory stack size (bytes)¶
/
Specify the size of the memory stack in bytes for each physical CPU. For example, if you specify 8 kilobytes, each CPU will get its own 8-kilobyte stack. (Default value is
0x2000
)An Integer value in hexadecimal format (with a leading
0x
).
Hypervisor capacities¶
Configure the capacities of the hypervisor.
- Max PCI devices¶
/
Specify the maximum number of PCI devices. This impacts the amount of memory used to maintain information about these PCI devices. The default value is calculated from the board configuration file. If you have PCI devices that were not detected by the Board Inspector, you may need to change this maximum value. (Default value is
96
)Integer from 1 to 1024.
- Max passthrough IRQ entries¶
/
Specify the maximum number of interrupt request (IRQ) entries from all passthrough devices. (Default value is
256
)Integer from 1 to 1024.
- Max MSI-X tables¶
/
Specify the maximum number of Message Signaled Interrupt MSI-X tables per device. The default value is calculated from the board configuration file. (Default value is
64
)Integer value from 1 to 2048.
- Max emulated MMIO regions¶
/
Specify the maximum number of emulated MMIO regions for device virtualization. The default value is calculated from the board configuration file. (Default value is
16
)Integer value from 1 to 128.
Virtual Machine Options¶
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 name¶
/
Specify the name used to identify this VM. The VM name will be shown in the hypervisor console vm_list command.
A string of up to 15 letters, digits,
_
, or-
.
- VM type¶
/
Select the VM type. A standard VM (
STANDARD_VM
) is for general-purpose applications, such as human-machine interface (HMI). A real-time VM (RTVM
) offers special features for time-sensitive applications.Current supported VM types are:
Real-time
for time-sensitive applications.Standard
for general-purpose applications, such as human-machine interface (HMI).
- Console virtual UART type¶
/
Select the console virtual UART (vUART) type. Add the console settings to the kernel command line by typing them in the “Linux kernel command-line parameters” text box (for example,
console=ttyS0
for COM port 1). (Default value isNone
)A string with either
None
,COM Port 1
,COM Port 2
,COM Port 3
, orPCI
.
- OS type¶
/
Select the OS type for this VM. This is required to run Windows in a User VM. See Device Model Parameters for how to include this in the Device Model arguments. (Default value is
Non-Windows OS
)A string with either
Non-Windows OS
orWindows OS
.
- Emulate COM1 as stdio I/O¶
/
Enable the ACRN Device Model to emulate COM1 as a User VM stdio I/O. Hypervisor global emulation will take priority over this VM setting. (Default value is
y
)A Boolean value, displayed as a check box.
- Enable Open Virtual Machine FW¶
/
Use virtual bootloader OVMF (Open Virtual Machine Firmware) to boot this VM. (Default value is
y
)A Boolean value, displayed as a check box.
Virtual USB HCI¶
Select the USB physical bus and port number that will be emulated by the ACRN Device Model for this VM. USB 3.0, 2.0, and 1.0 are supported.
- USB device assignment¶
/
Select the USB devices you want to assign to this virtual machine.
String value
- LAPIC passthrough¶
/
Enable LAPIC passthrough for this VM. This feature is required for VMs with stringent real-time performance needs. (Default value is
n
)A Boolean value, displayed as a check box.
- I/O completion polling¶
/
Enable polling mode for I/O completion for this VM. This feature is required for VMs with stringent real-time performance needs. (Default value is
n
)A Boolean value, displayed as a check box.
- Nested virtualization¶
/
Enable nested virtualization for KVM. (Default value is
n
)A Boolean value, displayed as a check box.
- Maximum virtual CLOS¶
/
Max number of virtual CLOS MASK (Default value is
0
)Integer value is not below zero.
- VM Virtual Cache Allocation Tech¶
/
Enable virtualization of the Cache Allocation Technology (CAT) feature in RDT. CAT enables you to allocate cache to VMs, providing isolation to avoid performance interference from other VMs. (Default value is
n
)A Boolean value, displayed as a check box.
Physical CPU affinity¶
Select a subset of physical CPUs that this VM can use. More than one can be selected.
clos¶
Class of Service for Cache Allocation Technology. Refer SDM 17.19.2 for details, and use with caution.
- vcpu_clos¶
/
By default (
virtual_cat_support
is not specified): vcpu_clos is per-CPU and it configures each CPU in VMs to a desired CLOS ID in theVM
section of the scenario file. Follow RDT Detection and Resource Capabilities to identify the maximum supported CLOS ID that can be used.If
virtual_cat_support
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 is0
)Integer value
SGX Enclave Page Cache¶
Specify the Intel Software Guard Extensions (SGX) enclave page cache (EPC) section settings.
- EPC section base¶
/
Specify the enclave page cache (EPC) section base for Intel Software Guard Extensions (SGX). Must be page aligned. (Default value is
0
)An Integer value in hexadecimal format (with a leading
0x
).
- EPC section size (bytes)¶
/
Specify the enclave page cache (EPC) section size in bytes for Intel Software Guard Extensions (SGX). Must be page aligned. (Default value is
0
)An Integer value in hexadecimal format (with a leading
0x
).
- Memory size (MB)¶
/
Specify the physical memory size allocated to this VM in megabytes. (Default value is
256
)Integer value is not below zero.
Physical memory segmentation¶
Specify Physical memory information for Prelaunched VM
- Start physical address¶
/
Specify the starting address for non-contiguous allocation.
An Integer value in hexadecimal format (with a leading
0x
).
- Size (MB)¶
/
Specify the physical memory size for non-contiguous allocation in megabytes. The size is a subset of the VM’s total memory size specified on the Basic tab.
Integer value
OS Configuration¶
General information for host kernel, boot argument and memory.
- Kernel image type¶
/
Select the kernel image type so that the hypervisor can load it correctly.
A string with either
KERNEL_BZIMAGE
orKERNEL_RAWIMAGE
.
- Kernel module tag¶
/
Specify the tag for the kernel image that is used as a multiboot module. The tag’s spelling must exactly match the module tag in the GRUB multiboot cmdline.
String value
- RAMdisk module tag¶
/
Specify the tag for the RAMdisk image that is used as a multiboot module. The tag’s spelling must exactly match the module tag in the GRUB multiboot cmdline.
String value
- Kernel command-line parameters¶
/
Specify the command-line parameters that will be used to boot the kernel for this VM. See Linux documentation for a list of parameters.
String value
MMIO Resources¶
MMIO resources to passthrough.
- TPM2 passthrough¶
/
Enable passthrough of the trusted platform module (TPM2) device to this VM. (Default value is
n
)A Boolean value, displayed as a check box.
- P2SB bridge passthrough¶
/
Enable passthrough of the Primary-to-Sideband (P2SB) bridge register access BAR to this VM. (Default value is
n
)A Boolean value, displayed as a check box.
PCI device assignment¶
- pci_dev¶
/
Select the PCI devices you want to assign to this virtual machine.
String value
- Virt-IO devices¶
/
Enable virt-IO devices in post-launched VMs.
Integer value
String value
- Virtio GPU device¶
/
The virtio GPU device presents a GPU device to the VM. This feature enables you to view the VM’s GPU output in the Service VM.
String value
- Virtio vsock CID¶
/
vsock is the new socket address family for host/guest communication. CID is the identifier for this VM.
Integer value
Virtio console device¶
Virtio console device for data input and output. The virtio console BE driver copies data from the frontend’s transmitting virtqueue when it receives a kick on virtqueue (implemented as a vmexit). The BE driver then writes the data to backend, and can be implemented as PTY, TTY, STDIO, and regular file. For details, see Virtio-Console.
- Use type¶
/
Specify device type in guest, ether HVC console when user config it as virtio console or /dev/vportXpY device file when user config it as virtio serial port, which can be read and written from the user space.
A string with value:
Virtio console
orVirtio serial port
- Backend type¶
/
Specify backend device type in service VM.
A string with value:
pty
,stdio
, orfile
.
- Output file path¶
/
The output file path for the file backend type.
String value
- Sock file path¶
/
The sock file path for the sock server or client backend type.
String value
- TTY device path¶
/
The device path for the tty backend type.
String value
Virtio network device¶
The virtio network device emulates a virtual network interface card (NIC) for the VM. The frontend
is the virtio network driver, simulating the virtual NIC. The backend could be: tap
device /dev/net/tun,
MacVTap
device /dev/tapx, or vhost
device /dev/vhost-net
- Virtio framework¶
/
Specify the virtio framework for specific virtio network device implemented in the Service VM. (Default value is
User space based (VBSU)
)A string with value:
Kernel based (Virtual Host)
orUser space based (VBSU)
.
- Network interface name¶
/
Specify the network interface name that will appear in the Service VM. Use the ip a command in the Service VM to display the network interface names.
A string of letters, digits,
_
, or-
.
Virtio input device¶
The virtio input device creates a virtual human interface device such as a keyboard, mouse, and tablet. It sends Linux input layer events over virtio.
- Backend device file¶
/
Specifying backend device in service vm with device description.
String value
- Guest virtio input device unique identifier¶
/
Specifying unique identifier to distinguish same devices in guest.
A string with letters, digits,
_
, or-
.
- Virtio block device¶
/
The virtio-blk device presents a block device to the VM. Each virtio-blk device appears as a disk inside the VM.
String value