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 v3.1 or v3.0.

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.

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.

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.

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.

Enable 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 n)

• A Boolean value, displayed as a check box.

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

Security VM Features

/

• This option enables hypervisor features potentially needed by a Security VM:

  • The virtual Trusted Platform Module (vTPM) 2.0 ACPI table, likely used by a security VM, is usually generated statically at build time. Checking this option enables the ACRN hypervisor to update the vTPM 2.0 ACPI table if the physical ACPI table was modified by the BIOS.

  • Data from the system management BIOS (SMBIOS) can replace probing hardware directly to discover what devices are present. Checking this option enables the hypervisor to pass through the physical SMBIOS to a pre-launched security VM.

  If your VM is not a security VM, leave this option unchecked. (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 ACPI 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 n)

• A Boolean value, displayed as a check box.

Enable MCE workaround

/

• Enable the software workaround for Machine Check Error on Page Size Change (erratum in some processor families). For more information about this workaround and affected processors, see this MCE Avoidance on Page Size Change White Paper. (Default value is y)

• A Boolean value, displayed as a check box.

Inter-VM shared memory

Configure shared memory regions for inter-VM communication.

IVSHMEM_REGION

Create a memory region for VMs to share: specify its name, size, and associated VMs.

Region Name

/

• Name of the shared memory region. The name must be between 1-27 characters and contain only letters, digits and “_”.

• Must be 1-27 characters and only letters, digits and “_”.

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.

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

• A string with value: legacy or pci.

Virtual UART port

vUART VM name

/

• Specify the VM name of one end point for this vUART connection.

• String value

Virtual I/O address

/

• Specify the COM base for each legacy virtual UART.

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

Debug options

Configure the debug facilities.

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

• 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 5)

• 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 5)

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

Memory options

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

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.

CACHE_REGION

Specify the cache setting.

CACHE_ALLOCATION

Cache ID

/

• The Cache Region index

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

Cache Level

/

• The Cache Region Level

• Integer value

POLICY

VM Name

/

• The Name of VM

• String value

Virtual CPU ID

/

• The Virtual CPU index of VM

• Integer value

Cache Type

/

• The Type of Cache Region

• Option: Unified, Code, Data

Cache CLOS Mask

/

• The Cache Region 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 is for general-purpose applications, such as human-machine interface (HMI). A Real-time VM offers special features for time-sensitive applications. (Default value is STANDARD_VM)

• Current supported VM types are:

  • Real-time for time-sensitive applications (not applicable to the service VM).

  • 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. (Default value is Non-Windows OS)

  See Device Model Parameters for how to include this in the Device Model arguments.

• 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 n)

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

Memory size (MB)

/

• Specify the physical memory size allocated to this VM in megabytes. (Default value is 1024)

• 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

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.

• Integer value

Real-time vCPU

/

• Check “Real-time vCPU” for each vCPU used for real-time workloads. Then configure cache usage in the Hypervisor/Advanced/Cache Allocation Technology (CAT) configuration option. There you’ll see Real-time vCPUs separated from vCPUs you allocate to other tasks. (Default value is n)

  See Enable Intel Resource Director Technology (RDT) Configurations for more details.

• A Boolean value, displayed as a check box.

USB device assignment

/

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

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

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.

Maximum virtual CLOS

/

• Max number of virtual CLOS MASK (Default value is 0)

• Integer value is not below zero.

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

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. (Default value is KERNEL_BZIMAGE)

• 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. (Default value is Linux_bzImage)

• 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. (Default value is rw rootwait root=/dev/nvme0n1p2 console=tty0 console=ttyS0 consoleblank=0 no_timer_check quiet loglevel=3 i915.nuclear_pageflip=1 swiotlb=131072)

• String value

MMIO Resources

Memory-mapped IO (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 devices

/

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

• 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 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 a PTY, TTY, STDIO, or 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. (Default value is Virtio console)

• A string with value: Virtio console or Virtio serial port

Backend type

/

• Specify backend device type in service VM. (Default value is stdio)

• 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, or tablet. The device 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

Virtio vsock Context ID (CID)

/

• Specify the post-launched VM’s unique Context ID (CID) used by vsock (integer greater than 2). vsock provides a way for the host system and applications running in a user VM to communicate with each other using the standard socket interface. vsock uses a (context id, port) pair of integers for identifying processes. The host system CID is always 2. The port is hardcoded in our implementation.

• Integer value