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

ACRN v3.3 (Aug 2024)

We are pleased to announce the release of the Project ACRN hypervisor version 3.3.

ACRN is a flexible, lightweight reference hypervisor that is built with real-time and safety-criticality in mind. It is optimized to streamline embedded development through an open-source platform. See the What Is ACRN introduction for more information.

All project ACRN source code is maintained in the https://github.com/projectacrn/acrn-hypervisor repository and includes folders for the ACRN hypervisor, the ACRN device model, tools, and documentation. You can download this source code either as a zip or tar.gz file (see the ACRN v3.3 GitHub release page) or use Git clone and checkout commands:

git clone https://github.com/projectacrn/acrn-hypervisor
cd acrn-hypervisor
git checkout v3.3

The project’s online technical documentation is also tagged to correspond with a specific release: generated v3.3 documents can be found at https://projectacrn.github.io/3.3/. Documentation for the latest development branch is found at https://projectacrn.github.io/latest/.

ACRN v3.3 requires Ubuntu 22.04. Follow the instructions in the Getting Started Guide to get started with ACRN.

What’s New in v3.3

Generic Main VM Support

The v3.3 release now supports a new scenario called “Main VM”. A “Service VM” has two characteristics: (1) it is the default owner of physical resources and (2) it can invoke VM management hypercalls. This release adds support to configure a VM with only the physical resource ownership characteristic and calling this a “Main VM”. An example scenario is a pre-launched TEE (Trusted Execution Environment) VM and a main REE (Rich Execution Environment) VM.

Enabling Celadon as User VM

The acrn hypervisor now supports Celadon as User VM OS. Celadon is an open-source project by Intel that provides a reference software stack for Android on Intel architecture platforms, aiming to enable developers to optimize and test Android on Intel-based devices.

Virtual Processor Performance Controls (vHWP)

The v3.3 release provides virtual HWP feature to a VM so that the VM can check hardware performance ranges and adjust performance levels for performance or power consumption.

Virtual Thermal Monitor and Software Controlled Clock Facilities

This release is able to virtualize processor thermal sensors and controls for thermal management in VMs.

Hypervisor Runtime Core PM

The v3.3 release enhances processor power management in the hypervisor at runtime to reduce power consumption when a core is idle.

Guest S3 Support

The v3.3 release supports suspend-to-RAM of post-launched VMs running with OVMF.

System Performance Optimization - Virtio-blk Multi-Virtqueue Support

This release optimizes the virtio-block backend performance by allowing multiple virtqueues between a frontend driver and the backend.

Notification of VM Events

Emit events (such as RTC changes and power cycles) to the monitor socket for customizing further actions upon such events.

Enhance device model passthrough

This release support passthrough PCI device with legacy interrupt, some ACPI device like GPIO controller, legacy UART.

ServiceVM supervisor role

User can config ServicVM as supervisor role in result it can manage the power status of any guest VM.

Upgrading to v3.3 from Previous Releases

We recommend you generate a new board XML for your target system with the v3.3 Board Inspector. You should also use the v3.3 Configurator to generate a new scenario XML file and launch scripts. Scenario XML files and launch scripts created by previous ACRN versions will not work with the v3.3 ACRN hypervisor build process and could produce unexpected errors during the build.

Given the scope of changes for the v3.3 release, we have recommendations for how to upgrade from prior ACRN versions:

  1. Start fresh from our Getting Started Guide. This is the best way to ensure you have a v3.3-ready board XML file from your target system and generate a new scenario XML and launch scripts from the new ACRN Configurator that are consistent and will work for the v3.3 build system.

  2. Use the upgrader tool to attempt upgrading your configuration files that worked with prior releases. You’ll need the matched pair of scenario XML and launch XML files from a prior configuration, and use them to create a new merged scenario XML file. See Upgrading ACRN Configurations to Recent Releases for details.

  3. Manually edit your previous older scenario XML and launch XML files to make them compatible with v3.3. This is not our recommended approach.

Here are some additional details about upgrading to the v3.3 release.

Generate New Board XML

Board XML files, generated by ACRN Board Inspector, contain board information that is essential for building the ACRN hypervisor and setting up User VMs. Compared to previous versions, ACRN v3.3 adds the following information to the board XML file for supporting new features and fixes:

  • Fix typo in PCIe PTM Capability name (See #8607)

  • Support motherboard which exposes MCFG1/MCFG2 instad of one ACPI MCFG table. (See #8513)

See the Board Inspector Tool documentation for a complete list of steps to install and run the tool.

Update Configuration Options

As explained in this Upgrading ACRN Configurations to Recent Releases document, we do provide a tool that can assist upgrading your existing pre-v3.3 scenario XML files in the new merged v3.3 format. From there, you can use the v3.3 ACRN Configurator UI to open the upgraded scenario file for viewing and further editing if the upgrader tool lost meaningful data during the conversion.

The ACRN Configurator adds the following features and fixes to improve the user experience:

  • Support Main VM configuration. (See #8658)

  • Change Service VM to supervisor role. (See #8630)

  • Fix Vue3 version and update braces version (See #8627)

  • Fix openssl’s vulnerability for tauri (See #8670)

  • Fix v-model used on props for Vue3 making strictly checking (See #8597)

  • Support vUART two options in configurator (See #8649)

  • Add checking cpu affinity and serial port for post-launch VM and hypervisor while the user click to append a new VM. (See #8602)

See the Scenario Configuration Options documentation for details about all the available configuration options in the new Configurator.

Document Updates

Here are some of the more significant documentation updates from the v3.2 release:

Fixed Issues Details

  • #8608 - hybrid vcpuid support

  • #8590 - Hypervisor crashes after rebooting post-launched vm with passthrogh device for lots of times

  • #8599 - Should clear pcpu_active_bitmap in start_pcpu

  • #8590 - Hypervisor crashes after rebooting post-launched vm with passthrogh device for lots of times

  • #8576 - Update-grub failed with GRUB 2.12

  • #8518 - Initial boot log is lost in vm_console

  • #8509 - S3 feature of Service VM OS is not available

  • #8506 - Unable to passthrough USB device on bus 5 to guest

  • #8500 - Add weight support for BVT scheduler

  • #8495 - Service VM dead loops when booting up on platform with reserved memory as the last e820 entry

  • #8492 - passthru multifunction device at function 0 will cause sub-function devices lost

  • #8537 - Emulate COM3/4 in devicemodel

  • #8491 - need to expose service vm config pointer

  • #8579 - debian: fix broken grub config with grub 2.12

  • #6631 - Fix Kata support with modify network configuration

Known Issues

  • #6978 - openstack failed since ACRN v2.7

  • #7827 - Pre_launched standard VMs cannot share CPU with Service VM in configurator

  • #8471 - PTM enabling failure on i225 NIC

  • #8472 - Failed to clear memory for post-launched standard VM