Important

This is the latest documentation for the unstable development branch of Project ACRN (master).
Use the drop-down menu on the left to select documentation for a stable release such as v2.7.

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

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
Find this option on the Configurator’s Hypervisor Global Settings tab	Find this option on the Hypervisor’s or VM’s Basic Parameters tab
Find this option on a Configurator Pre-Launched VM tab	Find this option on the Hypervisor’s or VM’s Advanced Parameters tab
Find this option on a Configurator Post-Launched VM tab
Find this option on the Configurator Service VM 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.

Inter-VM shared memory

Configure shared memory regions for inter-VM communication.

Region Name

/

• Name of the shared memory region.

• A string with no spaces.

Emulated by

/

• Whether the shared memory region is emulated by the hypervisor or Device Model. (Default value is Hypervisor)

• A string with value Hypervisor or Device Model.

Region Size (MB)

/

• Select the size of the shared memory region in megabytes. The value should be a power of 2 and no more than 512. (Default value is 2)

• An Integer with value a power of 2 between 2 and 512.

Shared VMs

/

• Name of the VM that uses this shared memory region.

• A string of up to 15 letters, digits, _, or -.

Virtual BDF

/

• Virtual BDF (Bus Device Function) is automatically assigned and can be changed if needed. Set in Hex.

• A string with up to two hex digits, a :, two hex digits, a ., and one digit between 0-7.

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 or Debug 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 messages

  • 5: 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 messages

  • 5: 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 messages

  • 5: 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 or pci.

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.

MISC_CFG

Miscellaneous options for workarounds.

CACHE_REGION

Specify the cache setting.

CACHE_ALLOCATION

CACHE_ID

/

• An Integer value in hexadecimal format (with a leading 0x).

CACHE_LEVEL

/

• Integer value

VM

/

• String value

VCPU

/

• Integer value

TYPE

/

• Option: Unified, Code, Data

CLOS_MASK

/

• An Integer value in hexadecimal format (with a leading 0x).

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 is None)

• A string with either None, COM Port 1, COM Port 2, COM Port 3, or PCI.

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 or Windows 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.

pCPU list

List of pCPU affinities.

pCPU ID

/

• ID of the pCPU that this VM’s vCPU is allowed to pin to. (Default value is 2)

• Integer value

Real-time vCPU

/

• Whether this vCPU is used for real-time-critical workloads. (Default value is n)

• A Boolean value, displayed as a check box.

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 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 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 is 0)

• 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 or KERNEL_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 or Virtio serial port

Backend type

/

• Specify backend device type in service VM.

• A string with value: pty, stdio, or file.

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) or User 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