Device Model Parameters

Hypervisor Device Model (DM) is a QEMU-like application in the Service VM responsible for creating a User VM and then performing devices emulation based on command line configurations, as introduced in Device Model High-Level Design.

Here are descriptions for each of these acrn-dm command line parameters:

-A, --acpi

Create ACPI tables. With this option, DM will build an ACPI table into its VMs F-Segment (0xf2400). This ACPI table includes full tables for RSDP, RSDT, XSDT, MADT, FADT, HPET, MCFG, FACS, and DSDT. All these items are programmed according to acrn-dm command line configuration and derived from their default value.


-B, --bootargs <bootargs>

Set the User VM kernel command-line arguments. The maximum length is 1023. The bootargs string will be passed to the kernel as its cmdline.

Example:

-B "loglevel=7"

specifies the kernel log level at 7

--debugexit

Enable guest to write io port 0xf4 to exit guest. It’s mainly used by guest unit test.


-E, --elf_file <elf image path>

This option is to define a static elf binary which could be loaded by DM. DM will run elf as guest of ACRN.


--enable_trusty

Enable trusty for guest. For Android guest OS, ACRN provides a VM environment with two worlds: normal world and trusty world. The Android OS runs in the the normal world. The trusty OS and security sensitive applications runs in the trusty world. The trusty world can see the memory of normal world but not vice versa. See Trusty TEE for more information.

By default, the trusty world is disabled. Use this option to enable it.


-h, --help

Show a summary of commands.


-i, --ioc_node <ioc_mediator_parameters>

IOC (IO Controller) is a bridge of an SoC to communicate with Vehicle Bus. It routes Vehicle Bus signals, for example extracted from CAN messages, from IOC to the SoC and back, as well as controlling the onboard peripherals from SoC. (The -i and -l parameters are only available on a platform with IOC.)

IOC DM opens /dev/ptmx device to create a peer PTY devices, IOC DM uses these to communicate with UART DM since UART DM needs a TTY capable device as its backend.

The device model configuration command syntax for IOC mediator is:

-i,[ioc_channel_path],[wakeup_reason]
-l,[lpc_port],[ioc_channel_path]
  • ioc_channel_path is an absolute path for communication between IOC mediator and UART DM.

  • lpc_port is com1 or com2. IOC mediator needs one unassigned lpc port for data transfer between User OS and Service OS.

  • wakeup_reason is IOC mediator boot reason, where each bit represents one wakeup reason.

Currently the wakeup reason bits supported by IOC firmware are:

  • CBC_WK_RSN_BTN (bit 5): ignition button.

  • CBC_WK_RSN_RTC (bit 9): RTC timer.

  • CBC_WK_RSN_DOR (bit 11): Car door.

  • CBC_WK_RSN_SOC (bit 23): SoC active/inactive.

As an example, the following commands are used to enable IOC feature, the initial wakeup reason is ignition button, and cbc_attach uses ttyS1 for TTY line discipline in User VM:

-i /run/acrn/ioc_$vm_name,0x20
-l com2,/run/acrn/ioc_$vm_name

--intr_monitor <intr_monitor_params>

Enable interrupt storm monitor for User VM. Use this option to prevent an interrupt storm from the User VM.

usage: --intr_monitor threshold/s probe-period(s) delay_time(ms) delay_duration(ms)

Example:

--intr_monitor 10000,10,1,100
  • 10000: interrupt rate larger than 10000/s will be treated as interrupt storm

  • 10: use the last 10s of interrupt data to detect an interrupt storm

  • 1: when interrupts are identified as a storm, the next interrupt will be delayed 1ms before being injected to the guest

  • 100: after 100ms, we will cancel the interrupt injection delay and restore to normal.


-k, --kernel <kernel_image_path>

Set the kernel (full path) for the User VM kernel. The maximum path length is 1023 characters. The DM handles bzImage image format.

usage: -k /path/to/your/kernel_image


-l, --lpc <lpc_device_configuration>

(See -i, --ioc_node)


-m, --memsize <memory_size>

Setup total memory size for User VM.

memory_size format is: “<size>{K/k, B/b, M/m, G/g}”, and size is an integer.

usage: -m 4g: set User VM memory to 4 gigabytes.


--mac_seed <seed_string>

Set a platform-unique string as a seed to generate the mac address. Each VM should have a different “seed_string”. The “seed_string” can be generated by the following method where $(vm_name) contains the name of the VM you are going to launch.

mac=$(cat /sys/class/net/e*/address)
seed_string=${mac:9:8}-${vm_name}

--part_info <part_info_name>

Set guest partition info path.


-r, --ramdisk <ramdisk_image_path>

Set the ramdisk (full path) for the User VM. The maximum length is 1023. The supported ramdisk format depends on your User VM kernel configuration.

usage: -r /path/to/your/ramdisk_image


-s, --pci_slot <slot_config>

Setup PCI device configuration.

slot_config format is:

<bus>:<slot>:<func>,<emul>[,<config>]
<slot>[:<func>],<emul>[,<config>]

Where:

  • slot is 0..31

  • func is 0..7

  • emul is a string describing the type of PCI device, e.g. virtio-net

  • config is an optional device-dependent string, used for configuration.

Examples:

-s 7,xhci,1-2,2-2

This configuration means the virtual xHCI will appear in PCI slot 7 in User VM. Any physical USB device attached on 1-2 (bus 1, port 2) or 2-2 (bus 2, port 2) will be detected by User VM and be used as expected. To determine which bus and port a USB device is attached, you could run lsusb -t in Service VM.

-s 9,virtio-blk,/root/test.img

This adds virtual block in PCI slot 9 and uses /root/test.img as the disk image.

For more information about emulated device types, see :ref:’emul_config’.


-U, --uuid <uuid>

Set UUID for a VM. Every VM is identified by a UUID. You can define that UUID with this option. If you don’t use this option, a default one (“d2795438-25d6-11e8-864e-cb7a18b34643”) will be used.

usage:

-u "42795636-1d31-6512-7432-087d33b34756"

set the newly created VM’s UUID to 42795636-1d31-6512-7432-087d33b34756


-v, --version

Show Device Model version.


--vsbl <vsbl_file_path>

Virtual Slim bootloader (vSBL) is the virtual bootloader supporting booting of the User VM on the ACRN hypervisor platform. The vSBL design is derived from Slim Bootloader, which follows a staged design approach that provides hardware initialization and launching a payload that provides the boot logic.

The vSBL image is installed on the Service OS root filesystem by the service-os bundle, in /usr/share/acrn/bios/. In the current design, the vSBL supports booting Android guest OS or Linux guest OS using the same vSBL image. For Android VM, the vSBL will load and verify trusty OS first, and trusty OS will then load and verify Android OS according to Android OS verification mechanism.

Note

vSBL is currently only supported on Apollo Lake processors.

usage:

--vsbl /usr/share/acrn/bios/VSBL.bin

uses /usr/share/acrn/bios/VSBL.bin as the vSBL image.


--ovmf [w,]<ovmf_file_path> --ovmf [w,]code=<ovmf_code_file>,vars=<ovmf_vars_file>

Open Virtual Machine Firmware (OVMF) is an EDK II based project to enable UEFI support for Virtual Machines.

ACRN does not support off-the-shelf OVMF builds targeted for QEMU and KVM. Compatible OVMF images are included in the source tree, under devicemodel/bios/.

usage:

--ovmf /usr/share/acrn/bios/OVMF.fd

uses /usr/share/acrn/bios/OVMF.fd as the OVMF image

ACRN also supports using OVMF split images; OVMF_CODE.fd that contains the OVMF firmware executable and OVMF_VARS.fd that contains the NV data store.

usage:

--ovmf code=/usr/share/acrn/bios/OVMF_CODE.fd,vars=/usr/share/acrn/bios/OVMF_VARS.fd

ACRN supports the option “w” for OVMF. To preserve all changes in OVMF’s NV data store section, use this option to enable writeback mode.

Writeback mode is only enabled for the OVMF_VARS.fd file in case of OVMF split images, the firmware executable (OVMF_CODE.fd) remains read-only.

usage:

--ovmf w,/usr/share/acrn/bios/OVMF.fd

--cpu_affinity <list of pCPUs>

list of pCPUs assigned to this VM.

Example:

--cpu_affinity 1,3

to assign physical CPUs (pCPUs) 1 and 3 to this VM.


--virtio_poll <poll_interval>

Enable virtio poll mode with poll interval xxx ns.

Example:

--virtio_poll 1000000

enable virtio poll mode with poll interval 1ms.


--acpidev_pt <HID>

This option is to enable ACPI device passthrough support. The HID is a mandatory parameter for this option which is the Hardware ID of the ACPI device.

Example:

--acpidev_pt MSFT0101

To pass through a TPM (which HID is MSFT0101) ACPI device to a User VM.


--mmiodev_pt <MMIO_Region>

This option is to enable MMIO device passthrough support. The MMIO_Region is a mandatory parameter for this option which is the MMIO resource of the MMIO device. The MMIO_Region needs to be the base address followed by the length of the region, both separated by a comma.

Example:

--mmiodev_pt 0xFED40000,0x00005000

To pass through a MMIO device to a User VM. The MMIO device has a MMIO region. The base address of this region is 0xFED40000 and the size of the region is 0x00005000.


--vtpm2 <sock_path>

This option is to enable virtual TPM support. The sock_path is a mandatory parameter for this option which is the path of swtpm socket fd.


-W, --virtio_msix

This option forces virtio to use single-vector MSI. By default, any virtio-based devices will use MSI-X as its interrupt method. If you want to use single-vector MSI interrupt, you can do so using this option.


-Y, --mptgen

Disable MPtable generation. The MultiProcessor Specification (MPS) for the x86 architecture is an open standard describing enhancements to both operating systems and firmware that allows them to work with x86-compatible processors in a multi-processor configuration. MPS covers Advanced Programmable Interrupt Controller (APIC) architectures.

By default, DM will create the MPtable for you. Use this option to disable it.


--lapic_pt

This option is to create a VM with the local APIC (LAPIC) passed-through. With this option, a VM is created with LAPIC_PASSTHROUGH and IO_COMPLETION_POLLING mode. This option is typically used for hard real-time scenarios.

By default, this option is not enabled.


--rtvm

This option is used to create a VM with real-time attributes. With this option, a VM is created with GUEST_FLAG_RT and GUEST_FLAG_IO_COMPLETION_POLLING mode. This kind of VM is generally used for soft real-time scenarios (without --lapic_pt) or hard real-time scenarios (with --lapic_pt). With GUEST_FLAG_RT, the Service VM cannot interfere with this kind of VM when it is running. It can only be powered off from inside the VM itself.

By default, this option is not enabled.


--logger_setting <console,level=4;disk,level=4;kmsg,level=3>

This option sets the level of logging that is used for each log channel. The general format of this option is <log channel>,level=<log level>. Different log channels are separated by a semi-colon (;). The various log channels available are: console, disk and kmsg. The log level ranges from 1 (error) up to 5 (debug).

By default, the log severity level is set to 4 (info).


--pm_notify_channel <channel>

This option is used to define which channel could be used DM to communicate with VM about power management event.

ACRN supports three channels: ioc, power_button and uart.

For uart, an additional option, ,allow_trigger_s5, can be added. A user can use this option to indicate the User VM is allowed to trigger system S5.

usage:

--pm_notify_channel ioc

Use ioc as power management event notify channel.


--pm_by_vuart [pty|tty],<node_path>

This option is used to set a user OS power management by virtual UART. With acrn-dm UART emulation and hypervisor UART emulation and configure, service OS can communicate with user OS through virtual UART. By this option, service OS can notify user OS to shutdown itself by vUART.

It must work with –pm_notify_channel and PCI UART setting (lpc and -l).

Example:

for general User VM, such as LaaG or WaaG, it must set:
   --pm_notify_channel uart --pm_by_vuart pty,/run/acrn/life_mngr_vm1
   -l com2,/run/acrn/life_mngr_vm1
for RTVM, like RT-Linux:
   --pm_notify_channel uart --pm_by_vuart tty,/dev/ttyS1

For a different User VM, it can be configured as needed.

--windows

This option is used to run Windows User VMs. It supports Oracle virtio-blk, virtio-net and virtio-input devices for Windows guests with secure boot.

usage:

--windows

Note

This option is mandatory for running Windows in a User VM. If it is not used, Windows will not recognize the virtual disk.


--ssram

This option enables Software SRAM passthrough to the VM.

usage:

--ssram

Emulated PCI Device Types

In the acrn-dm -s or --pci_slot command line parameter, there is a <slot_config> argument that contains a string describing the type of emulated PCI device, along with optional device-dependent arguments used for configuration. Here is a table describing these emulated device types and arguments:

Table 2 Emulated PCI Device Types

PCI Device Type string

Description

xhci

USB controller used to support USB 3.0 devices, (also supports USB 2.0 and USB 1.0 devices). Parameter <bus number>-<port number> should be added. The physical USB devices attached on the specified bus and port will be detected by User VM and used as expected, e.g., xhci,1-2,2-2.

lpc

Low Pin Count (LPC) bus is used to connect low speed devices to the CPU, for example a serial port, keyboard, or mouse.

igd-lpc

Windows graphic driver requires this virtualized LPC device to operate the display function.

ivshmem

Inter-VM shared memory (ivshmem) virtualized PCI device used specifically for shared memory between VMs. Parameters should be added with the format ivshmem,<shm_name>,<shm_size>. <shm-name> specifies a shared memory name, and must be listed in hv.FEATURES.IVSHMEM.IVSHMEM_REGION as configured using the ACRN configurator tool UI, and needs to start with a dm:/ prefix.

ahci

Advanced Host Controller Interface provides advanced features to access Serial ATA (SATA) storage devices, such as a hard disk. Parameter <type:><filepath>* should be added: type could be hd (harddisk) or cd (CD-ROM). <filepath> is the path for the backend file and could be a partition name or a regular file, e.g., ahci,hd:/dev/sda.

ahci-hd

This is an alias for ahci.

ahci-cd

Advanced Host Controller Interface used to connect with AT Attachment Packet Interface device (for CD-ROM emulation). ahci-cd supports the same parameters than ahci.

amd_hostbridge

Virtualized PCI AMD hostbridge

hostbridge

Virtualized PCI hostbridge, a hardware bridge between the CPU’s high-speed system local bus and the Peripheral Component Interconnect (PCI) bus.

virtio-blk

Virtio block type device, a string could be appended with the format virtio-blk,[,b,]<filepath>[,options]

  • [,b,] specifies a bootable device and the bootable image location when using vsbl as the virtual bootloader.

  • <filepath> specifies the path of a file or disk partition. You can also could use nodisk to create a virtio-blk device with a dummy backend. nodisk is used for hot-plugging a rootfs after the User VM has been launched. It is achieved by triggering a rescan of the virtio-blk device by the User VM. The empty file will be updated to valid file after rescan.

  • [,options] includes:

    • writethru: write operation is reported completed only when the data has been written to physical storage.

    • writeback: write operation is reported completed when data is placed in the page cache. Needs to be flushed to the physical storage.

    • ro: open file with readonly mode.

    • sectorsize: configured as either sectorsize=<sector size>/<physical sector size> or sectorsize=<sector size>. The default values for sector size and physical sector size are 512.

    • range: configured as range=<start lba in file>/<sub file size> meaning the virtio-blk will only access part of the file, from the <start lba in file> to <start lba in file> + <sub file site>.

virtio-coreu

Used for Protected Audio Visual Path (PAVP) session management to provide a User VM with Protected Audio Visual Path service.

virtio-input

Virtio type device to emulate input device. evdev char device node should be appended, e.g., -s n,virtio-input,/dev/input/eventX[,serial]. serial is an optional string used as the unique identification code of guest virtio input device.

virtio-ipu

Virtio image processing unit (IPU), it is used to connect camera device to system, to convert the raw Bayer image into YUV domain.

virtio-console

Virtio console type device for data input and output.

virtio-hyper_dmabuf

Virtio device that allows sharing data buffers between VMs using a dmabuf-like interface.

virtio-hdcp

Virtio High-bandwidth Digital Content Protection (HDCP) type device. HDCP is technology intended to protect unauthorized duplication of high definition (HD) video and audio as it travels across connections.

virtio-heci

Virtio Host Embedded Controller Interface, parameters should be appended with the format <bus>:<device>:<function>,d<0~8>. You can find the BDF information from the Service VM.

virtio-i2c

Virtio i2c type device,parameters with format: <bus>[:<client_addr>[@<node>]][,<bus>[:<client_addr>[@<node>]]

  • <bus> specifies the bus number for the native I2C adapter, e.g., 2 means /dev/i2c-2.

  • <client_addr> specifies the address for the native client devices such as 1C or 2F.

  • @ specifies the prefix for the ACPI node.

  • <node> specifies the ACPI node name supported in the acpi_node_table[] in the source code: only cam1, cam2, and hdac are supported for APL platform and are platform-specific.

virtio-gpio

Virtio GPIO type device, parameters format is: virtio-gpio,<@controller_name{offset|name[=mapping_name]:offset|name[=mapping_name]:...}@controller_name{...}...]>

  • controller_name: use the command ls /sys/bus/gpio/devices to check the native GPIO controller information. Usually, the devices represent the controller_name that you can use. You can also use the command cat /sys/bus/gpio/device/XXX/dev to get the device id that can be used to match /dev/XXX, and then use XXX as the controller_name. On Intel platforms, controller_name may be gpiochip0, gpiochip1, gpiochip2, and gpiochip3.

  • offset|name: use GPIO offset or its name to locate one native GPIO within the GPIO controller.

  • mapping_name: is optional. If you want to use a customized name for a FE GPIO, you can set a new name here.

virtio-rnd

Virtio random generater type device, with string kernel=on to select the VBSK virtio backend. The VBSU virtio backend is used by default.

virtio-rpmb

Virtio Replay Protected Memory Block (RPMB) type device, with physical_rpmb to specify RPMB in physical mode, otherwise RPMB is in simulated mode.

virtio-audio

Virtio audio type device

virtio-net

Virtio network type device, parameter should be appended with the format: virtio-net,<device_name>,[vhost],[mac=<XX:XX:XX:XX:XX:XX>]. The mac address is optional, device_name is the name of the TAP (or MacVTap) device. It must include the keyword tap. vhost specifies vhost backend, otherwise the VBSU backend is used.

passthru

Indicates a passthrough device. Use the parameter with the format passthru,<bus>/<device>/<function>,<optional parameter> Optional parameters include:

  • keep_gsi: keep vGSI for MSI capable passthrough device.

  • no_reset: passthrough PCI devices are reset by default when assigning them to a post-launched VM. This parameter prevents this reset for debugging purposes.

  • d3hot_reset: when launching a Windows post-launched VM, this parameter should be appended to enable a Windows UEFI ACPI bug fix.

  • gpu: create the dedicated igd-lpc on 00:1f.0 for IGD passthrough.

  • vmsix_on_msi,<bar_id>: enables vMSI-X emulation based on MSI capability. The specific virtual bar will be allocated.

  • enable_ptm: enable PCIE precise time measurement mechanism for the passthrough device.

uart

Emulated PCI UART. Use the parameter with the format uart,vuart_idx:<0~9> to specify hypervisor-emulated PCI vUART index.

npk

Intel Trace Hub (known as North Peak or NPK) is a set of hardware blocks that produce, switch, and output trace data from multiple hardware, firmware, and software sources, used to perform full system debugging. Parameter with the format npk,<master_offset>/<master number> specifies the master offset in the physical STMR of the host, and the master number owned by the User VM.

wdt-i6300esb

Emulated i6300ESB PCI Watch Dog Timer (WDT) Intel processors use to monitor User VMs.