ACRN v3.1 (Sep 2022)¶
We are pleased to announce the release of the Project ACRN hypervisor version 3.1.
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.1 GitHub release page) or
use Git clone and checkout commands:
git clone https://github.com/projectacrn/acrn-hypervisor
cd acrn-hypervisor
git checkout v3.1
The project’s online technical documentation is also tagged to correspond with a specific release: generated v3.1 documents can be found at https://projectacrn.github.io/3.1/. Documentation for the latest development branch is found at https://projectacrn.github.io/latest/.
ACRN v3.1 requires Ubuntu 20.04. Follow the instructions in the Getting Started Guide to get started with ACRN.
What’s New in v3.1¶
- More ACRN Configuration Improvements
Release v3.0 featured a new ACRN Configurator UI tool with a more intuitive design and workflow that simplifies getting the setup for the ACRN hypervisor right. With this v3.1 release, we’ve continued making improvements to the Configurator including more comprehensive error checking with more developer-friendly messages. You’ll also see additional advanced configuration settings for tuning real-time performance including Cache Allocation Technology (CAT) and vCPU affinity. Read more in the ACRN Configurator Tool and Scenario Configuration Options documents.
If you have feedback on this, or other aspects of ACRN, please share them on the ACRN users mailing list.
As with the v3.0 release, we’ve simplified installation of the Configurator by providing a Debian package that you can download from the ACRN v3.1 tag assets and install. See the Getting Started Guide for more information.
- Improved Board Inspector Collection and Reporting
You run the ACRN Board Inspector tool to collect information about your target system’s processors, memory, devices, and more. The generated board XML file is used by the ACRN Configurator to determine which ACRN configuration options are possible, as well as possible values for target system resources. The v3.1 Board Inspector has improved scanning and provides more messages about potential issues or limitations of your target system that could impact ACRN configuration options.
The Board Inspector is updated to probe beyond CPUID information for Cache Allocation Technology (CAT) support and also detects availability of L3 CAT by accessing the CAT MSRs directly. Read more in Board Inspector Tool.
- Sample Application with Two Post-Launched VMs
With this v3.1 release, we provide a follow-on Sample Application User Guide to the Getting Started Guide. This sample application shows how to create two VMs that are launched on your target system running ACRN. One VM is a real-time VM running cyclictest, an open-source application commonly used to measure latencies in real-time systems. This real-time VM (RT_VM) uses inter-VM shared memory (IVSHMEM) to send data to a second Human-Machine Interface VM (HMI_VM) that formats and presents the collected data as a histogram on a web page shown by a browser. This guide shows how to configure, create, and launch the two VM images that make up this application. Full code for the sample application is provided in the
acrn-hypervisorGitHub repo misc/sample_application.- Multiple-Displays Support for VMs
The virtio-gpu mechanism is enhanced to support VMs with multiple displays.
- Improved TSC Frequency Reporting
The hypervisor now reports Time Stamp Counter (TSC) frequency in KHz so that VMs can get that number without calibrating to a high precision timer.
Upgrading to v3.1 from Previous Releases¶
We recommend you generate a new board XML for your target system with the v3.1 Board Inspector. You should also use the v3.1 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.1 ACRN hypervisor build process and could produce unexpected errors during the build.
Given the scope of changes for the v3.1 release, we have recommendations for how to upgrade from prior ACRN versions:
Start fresh from our Getting Started Guide. This is the best way to ensure you have a v3.1-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.1 build system.
Use the upgrader tool to attempt upgrading configuration files that worked with a release before v3.1. 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.
Manually edit your prior scenario XML and launch XML files to make them compatible with v3.1. This is not our recommended approach.
Here are some additional details about upgrading to the v3.1 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.1 adds the following information to the board XML file for supporting new features and fixes:
Probe and detect availability of L3 CAT by accessing the CAT MSRs directly
Refactor MSR utilities
Record all details from the real-time configuration table (RTCT) in the board XML and generate vRTCT instead of copying a physical one
The v3.1 Board Inspector includes a progress bar and timeout mechanism, as well as more developer-friendly logs and error messages. 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.1 scenario XML files in the new merged v3.1 format. From there, you can use the v3.1 ACRN Configurator to open the upgraded scenario file for viewing and further editing if the upgrader tool lost meaningful data during the conversion.
As part of the developer experience improvements to ACRN configuration, the following XML elements were refined in the scenario XML file:
ENFORCE_TURNOFF_ACis nowSPLIT_LOCK_DETECTION_ENABLED.ENFORCE_TURNOFF_GPis nowUC_LOCK_DETECTION_ENABLED.MCE_ON_PSC_DISABLEDis nowMCE_ON_PSC_ENABLED.
See the Scenario Configuration Options documentation for details about all the available configuration options in the new Configurator.
Document Updates¶
- Sample Application User Guide
The new Sample Application User Guide documentation shows how to configure, build, and run a practical application with a Real-Time VM and Human-Machine Interface VM that communicate using inter-VM shared memory.
We’ve also made edits throughout the documentation to improve clarity, formatting, and presentation. We started updating feature enabling tutorials based on the new Configurator, and will continue updating them after the v3.1 release (in the latest documentation). Here are some of the more significant updates:
Fixed Issues Details¶
8162 - dm: virtio-blk parameter error
8125 - [hypercube][ADL]Assertion’0’ failed found during hypercube_PIO_SCAN testing
8111 - [life_mngr] Sync between SOS and RTVM failed when startup hence life_mngr cannot work
7948 - Tiger Lake product with CAT enabled needed
8063 - Need to generate config_summary.rst
8098 - configurator build has dependency on published release documentation
8087 - ACRN Configurator enable RDT and CDP after launch scenario
8066 - User VM doesn’t have IP if launched by acrnd with virtio-net
7563 - [ADL-S][SSRAM]RTCM Unit run failed with 2G memory size
8068 - [config_tool] Imported scenarios not populating CAT widget
7973 - config-tools: User concern about the progress of generating board.xml and not sure whether need exit after waiting some time.
7975 - GSG python package xmlschema/elementpath incompatibility
8050 - config_tools: cpu affinity
8051 - ADL-S][S5]Can’t shutdown WaaG with user VM name same as in launch script
8046 - [config_tool] Configurator creates duplicate VM name
8018 - config-tools: default value & MAX_PCI_BUS_NUM
7991 - [Workshop] Configurator create scenario popup window disappear sometimes.
8033 - [config_tool] vUART widget address for pre-launched VM doesn’t update or display error
8000 - [config_tool] Real-time vCPU checkbox is confusing to users
7898 - [config_tool] Warning message when users attempt to create a new scenario or import an existing scenario for an existing configuration
5692 - Keep Open: Used when updating config option documentation in .xsd files
7914 - [config_tool] Focus change to new VM when added
7661 - config-tools: Change MCE AC and UC (GP) to enable
7927 - [acrn-configuration-tool] ACRN-Configurator does not consider L3 CAT config when opening an exiting configuration
7958 - [configurator] Need highlight success or fail status in the popup window of save scenario button
7913 - config-tools: build acrn successfully even set the same memory address between the pre vm 0 and hv
7931 - Improve HV console as a bash-like one
7960 - dm cannot stop correctly
7935 - Build EFI-Stub fail
7921 - [config_tool] Cache widget: Instructions missing for L2-only users
7925 - [configurator] invalid virtual bdf in ivshmem could be saved
7942 - [config_tool] vUART and IVSHMEM widgets don’t generate address
7947 - Need optimize user flow to configure SSRAM for pre-launched RTVM
7944 - Service VM hang when reboot user VM
7940 - DM: add support for iothread
7933 - [config_tool] Add tooltips to CPU affinity virtio
7926 - [acrn-configuration-tool]Memory warning when build ACRN for WHL
7902 - coding style cleanup in pci.c
7917 - [config_tool] Order of plus and minus icons is inconsistent
7790 - User VM fail to get IP with vhost net
7759 - ERROR: LeakSanitizer: detected memory leaks found when run
7915 - [config_tool] Duplicate VM error message - add spacing
7906 - config-tools: Board inspector crashed when command line is too long in dmesg
7907 - RRSBA should be disabled on platform using retpoline if enumerated
7897 - [config_tool] Placement of plus icon for virtio
7582 - configurator: board name truncated incorrectly
7707 - configurator: IVSHMEM region name lacks pattern check
7886 - config-tools: need to hide the ‘update-pciids: download failed’ message
7559 - Copyright year range in code headers is not up to date
7884 - config_tool: Move “BIOS Revision” line in Configurator UI
7893 - [config_tool] Incompatibility with latest elementpath library
7887 - hv: Surges of external interrupts may cause guest hang
7880 - fail to run acrn-dm with wrong iasl path