ACRN v2.4 (Apr 2021)¶
We are pleased to announce the release of the Project ACRN hypervisor version 2.4.
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.4 GitHub release page) or
use the Git
git clone https://github.com/projectacrn/acrn-hypervisor cd acrn-hypervisor git checkout v2.4
The project’s online technical documentation is also tagged to correspond with a specific release: generated v2.4 documents can be found at https://projectacrn.github.io/2.4/. Documentation for the latest under-development branch is found at https://projectacrn.github.io/latest/.
ACRN v2.4 requires Ubuntu 18.04. Follow the instructions in the Getting Started Guide to get started with ACRN.
What’s New in v2.4¶
Extensive work was done to redesign how ACRN configuration is handled, update the build process to use the new configuration system, and update the corresponding documentation. This is a significant change and improvement to how you configure ACRN but also impacts existing projects, as explained in the next section.
We’ve also validated the hybrid_rt scenario on the next generation of Intel® Core™ processors (codenamed Elkhart Lake) and enabled software SRAM and cache locking for real time performance on Elkhart Lake.
ACRN Configuration and Build¶
The following major changes on ACRN configuration and build process have been integrated into v2.4:
Metadata of configuration entries, including documentation and attributes, has been removed from
The C sources generated from
scenarioXMLs are no longer maintained in the repository. Instead they’ll be generated as part of the hypervisor build. Users can now find them under
configs/of the build directory.
Kconfig is no longer used for configuration. Related build targets, such as
defconfig, now apply to the configuration files in XML.
BOARD_FILEhave been unified. Users can now specify
xxxbeing either a board name or a (relative or absolute) path to a board XML file.
SCENARIO_FILEhave been unified in the same way.
For complete instructions to get started with the new build system, refer to Build ACRN From Source. For an introduction on the concepts and workflow of the new configuration mechanism, refer to Introduction to ACRN Configuration.
Upgrading to v2.4 From Previous Releases¶
We highly recommended that you follow the instructions below to upgrade to v2.4 from previous ACRN releases.
Python version 3.6 or higher is required to build ACRN v2.4. You can check the version of Python you are using by:
$ python3 --version Python 3.5.2
Only when the reported version is less than 3.6 (as is the case in the example above) do you need an upgrade. The first (and preferred) choice is to install the latest Python 3 from the official package repository:
$ sudo apt install python3 ... $ python --version Python 3.8.8
If this does not get you an appropriate version, you may use the deadsnakes PPA (using the instructions below) or build from source yourself.
$ sudo add-apt-repository ppa:deadsnakes/ppa $ sudo apt-get update $ sudo apt install python3.9 $ python --version Python 3.9.2
In addition, the following new tools and packages are needed to build ACRN v2.4:
$ sudo apt install libxml2-utils xsltproc $ sudo pip3 install lxml xmlschema
This is not the complete list of tools required to build ACRN. Refer to Build ACRN From Source for a complete guide to get started from scratch.
Configuration File Format¶
Starting with release v2.4, Kconfig is no longer used, and the contents of scenario XML files have been simplified. You need to upgrade your own Kconfig-format files or scenario XML files if you maintain any.
For Kconfig-format file, you must translate your configuration to a scenario XML file where all previous Kconfig configuration entries are also available. Refer to Scenario Configuration Options for the full list of settings available in scenario XML files.
For scenario XML files, you need to remove the obsolete metadata in those files. You can use the following XML transformation (in XSLT) for this purpose:
<?xml version="1.0" encoding="utf-8"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template match="@desc" /> <xsl:template match="@configurable | @multiselect | @readonly" /> <!-- The identity template --> <xsl:template match="@*|node()"> <xsl:copy> <xsl:apply-templates select="@*|node()"/> </xsl:copy> </xsl:template> </xsl:stylesheet>
After saving the snippet above to a file (e.g.,
xsltproc to clean and transform your own scenario XML file:
$ xsltproc -o <path/to/output> remove_metadata.xsl <path/to/your/XML>
New Configuration Options¶
The following element is added to scenario XML files in v2.4:
To upgrade a v2.3-compliant scenario XML file, you can use the following XML transformation. The indentation in this transformation are carefully tweaked for the best indentation in converted XML files.
<?xml version="1.0" encoding="utf-8"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template match="hv/FEATURES/MULTIBOOT2"> <xsl:copy> <xsl:apply-templates select="@*|node()"/> </xsl:copy> <xsl:if test="not(../ENFORCE_TURNOFF_AC)"> <xsl:text> </xsl:text> <ENFORCE_TURNOFF_AC>y</ENFORCE_TURNOFF_AC> </xsl:if> </xsl:template> <!-- The identity template --> <xsl:template match="@*|node()"> <xsl:copy> <xsl:apply-templates select="@*|node()"/> </xsl:copy> </xsl:template> </xsl:stylesheet>
We recommend you update the usage of variables
SCENARIO_FILE, which are being deprecated, and
BOARD_FILEshould be replaced with
BOARD. You should not specify
BOARD_FILEat the same time.
SCENARIO_FILEshould be replaced with
The value of
RELEASEshould be either
SCENARIO_FILE can still be used but will take effect
SCENARIO are not defined. They will be deprecated in
a future release.
Patches on Generated Sources¶
The C files generated from board and scenario XML files have been removed from the repository in v2.4. Instead they will be generated in the build output when building the hypervisor.
Typically you should be able to customize your scenario by modifying the scenario XML file rather than the generated files directly. But if that is not possible, you can still register one or more patches that will be applied to the generated files by following the instructions in Makefile Targets for Configuration.
Modifying generated files is not a recommended practice. If you find a configuration that is not flexible enough to meet your needs, please let us know by sending mail to the acrn-dev mailing list or submitting a GitHub issue.
With the changes to ACRN configuration noted above, we made substantial updates to the ACRN documentation around configuration and options, as listed here:
Additional new or updated reference documents are also available, including:
We’ve also made edits throughout the documentation to improve clarity, formatting, and presentation throughout the ACRN documentation.
Fixed Issues Details¶
5626 - [CFL][industry] Host Call Trace once detected
5672 - [EHL][v2.4][config_tools] Pop error message while config multi_ivshmem_device.
5689 - [EHL][SBL] copy GPA error when booting zephyr as pre-launched VM
5712 - [CFL][EHL][Hybrid-rt][WAAG]Post Launch WAAG with USB_Mediator-USB3.0 flash disk/SSD with USB3.0 port .waag cannot access USB mass storage
5717 - [WaaG Ivshmem] windows ivshmem driver does not work with hv land ivshmem
5719 - [EHL][[Hybrid RT] it will pop some warning messages while launch vm
5736 - Launch script: Remove –pm_notify_channel uart parameter in launch script
5772 - The RELEASE variable is not correctly handled
5778 - [EHL][v2.4] Failed to build hv with hypervisor_tools_default_setting _for newboard
5798 - [EHL][V2.4][[Fusa Partition] cannot disable AC after modify AC configuration in Kconfig
5802 - [EHL][syzkaller]HV crash with info ” rcu detected stall in corrupted” during fuzzing testing
5806 - [TGL][PTCM]Cache was not locked after post-RTVM power off and restart
5818 - [EHL][v2.4_rc1] Failed to boot up WAAG randomly
5863 - config-tools: loosen IVSHMEM_REGION restriction in schema
5369 - [TGL][qemu] Cannot launch qemu on TGL
5705 - [WindowsGuest] Less memory in the virtual machine than the initialization
5879 - hybrid_rt scenario does not work with large initrd in pre-launched VM
5888 - Unable to launch vm at the second time with pty,/run/acrn/life_mngr_$vm_name parameter added in the launch script