ACRN v2.5 (Jun 2021)

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

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 either download this source code as a zip or tar.gz file (see the ACRN v2.5 GitHub release page) or use Git clone and checkout commands:

git clone https://github.com/projectacrn/acrn-hypervisor
cd acrn-hypervisor
git checkout v2.5

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

ACRN v2.5 requires Ubuntu 18.04. Follow the instructions in the Getting Started Guide to get started with ACRN.

What’s New in v2.5

Nested Virtualization Technology Preview

A brand-new concept, nested virtualization, is introduced as a preview in this v2.5 release. Nested virtualization lets you run virtual machine instances inside of a guest VM that’s running on the ACRN hypervisor. It’s designed to leverage the KVM/QEMU community’s rich feature set while keeping ACRN’s unique advantages in partition mode and hybrid mode. Read more in the Enable Nested Virtualization advanced guide.

Secure Boot Using EFI Stub

EFI stub, previously retired in favor of using direct boot, returns as an alternative to end-to-end secure boot with Grub. The hypervisor, Service VM kernel, and prelaunched VM kernel are packaged into a single acrn.efi blob as an EFI application that can then be verified by the EFI BIOS. Read more in the Enable ACRN Secure Boot With EFI-Stub and Enable ACRN Secure Boot With GRUB advanced guides.

Modularization Improvements

ACRN hypervisor modularization has been improved to be more scalable, including change to multiboot, interrupt handling, paging and memory management, and timers, with more to come in future releases.

Configuration and Build Process Improvements

The ACRN configuration and build process continues to evolve from the changes made in the previous releases. For instructions using the build system, refer to Getting Started Guide. For an introduction on the concepts and workflow of the configuration tools and processes, refer to Introduction to ACRN Configuration.

Upgrading to v2.5 From Previous Releases

We highly recommended that you follow these instructions to upgrade to v2.5 from previous ACRN releases.

Generate New Board XML

Board XML files, generated by ACRN board inspector, contain board information that is essential to build ACRN. Compared to previous versions, ACRN v2.5 extends the schema of board XMLs to summarize board information more systematically. You must regenerate your board XML file using the new board inspector when you upgrade to ACRN v2.5 to get the additional information needed for configuration.

Before using the new board inspector, ensure you have Python >= 3.6 on the target board and install the lxml PyPI package. Refer to Additional Dependencies for detailed steps to check and upgrade your Python version. The lxml package can be installed by executing the following command:

sudo pip3 install lxml

Note

Refer to Getting Started Guide for a complete list of tools required to run the board inspector.

With the prerequisites done, copy the entire board inspector folder from misc/config_tools/board_inspector to the target board, cd to that directory on the target, and run the board inspector tool using:

sudo python3 cli.py <my_board_name>

This will generate <my_board_name>.xml in the current working directory. You’ll need to copy that XML file back to the host system to continue development.

Add New Configuration Options

In v2.5, the following elements are added to scenario XML files:

• hv.FEATURES.NVMX_ENABLED

• vm.PTM

The following element is renamed:

• hv.FEATURES.SSRAM.SSRAM_ENABLED (was hv.FEATURES.PSRAM.PSRAM_ENABLED in v2.4)

Constraints on values of the following element have changed:

• vm.guest_flags.guest_flag no longer accepts an empty text. For VMs with no guest flag set, set the value to 0.

Document Updates

With the changes to ACRN configuration, we made updates to the ACRN documentation around configuration, options, and parameters:

• Introduction to ACRN Configuration

• Scenario Configuration Options

• Device Model Parameters

• ACRN Kernel Parameters

New capabilities are documented here:

• Enable Nested Virtualization

We’ve also made edits throughout the documentation to improve clarity, formatting, and presentation throughout the ACRN documentation:

• Contribution Guidelines

• Documentation Guidelines

• AHCI Virtualization in Device Model

• Device Passthrough

• Hypercall / HSM Upcall

• Timer

• L1 Terminal Fault Mitigation

• ACRN Hypervisor: Modular Design

• Software Design Guidelines

• Trusty TEE

• Getting Started Guide

• Getting Started Guide

• Supported Hardware

• Enable ACRN Over QEMU/KVM

• ACRN Documentation Generation

• Enable Inter-VM Communication Based on Ivshmem

• Run Debian as the Service VM

• Trusty and Security Services Reference

• Getting Started Guide for ACRN Hybrid Mode

• Enable Serial Port on NUC

Fixed Issues Details

• 5626 - [CFL][industry] Host Call Trace once detected

• 5879 - hybrid_rt scenario does not work with large initrd in pre-launched VM

• 6015 - HV and DM: Obsolete terms cleanup for SSRAM

• 6024 - config-tools: generate board_info.h and pci_dev.c using xslt

• 6034 - dm: add allow_trigger_s5 mode to pm_notify_channel uart

• 6038 - [REG][RAMDISK] Fail to launch pre RTVM while config ramdisk

• 6056 - dm: a minor bug fix of unregister_mem_int

• 6072 - [WHL][WAAG]use config tool to passthru Audio,will not display GOP

• 6075 - [config_tools][regression][v2.5_rc1] config tool failed to save industry.xml with GuestFlagsOptionsType check

• 6078 - Make ACRN HV with hybrid_rt bootable without GRUB on UEFI BIOS

• 6100 - virtio_net_ping_rxq SEGV on read from NULL

• 6102 - Build failure for BOARD=qemu SCENARIO=sdc on release_2.5

• 6104 - [acrn-configuration-tool] Need update tgl-rvp.xml to the latest BIOS info

• 6113 - [config_tools][ADL-S]generated board xml parse error on ADL-S

• 6120 - [acrn-configuration-tool] shall we add CLOS_MASK elements into tgl scenario files as default configuration

• 6126 - TPM do not support dynamic GPA

• 6129 - virtio: NULL deref in hw/pci/virtio/virtio.c:664 in vq_endchains

• 6131 - guest/vlapic fatal assertion reachable from guest - DoS

• 6134 - [acrn-configuration-tool] lxml module not found when get board xml following doc

• 6138 - config-tools: support of launch script to generate the “allow_trigger_s5” automatically

• 6147 - ASAN reports UAF + SEGV when fuzzing exposed PIO with Hypercube guest VM.

• 6157 - coding style fix on v2.5 branch

• 6162 - [REG][EHL][SBL] Fail to boot sos

• 6168 - SOS failed to boot with nest enabled

• 6172 - member access within null pointer of type ‘struct xhci_trb’

• 6178 - config-tools: adding an empty node <pt_intx> for a pre-launched VM causing check_pt_intx throw out an error

• 6185 - [TGL][Industry]yaag can’t get ip after SRIVO VF passthru

• 6186 - [acrn-configuration-tool] CONFIG_MAX_MSIX_TABLE_NUM value is auto set as 64 when generate an new scenario xml

• 6199 - [doc][buildSource] can not pass SCENARIO parameter into hypervisor/build/.config with “make defconfig”

Known Issues

• 6256 - [TGL][qemu] Cannot launch qemu on TGL

• 6257 - [S5]S5 fails on post-launched RTVM