ACRN v3.0 (Jun 2022)¶
We are pleased to announce the release of the Project ACRN hypervisor version 3.0.
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.0 GitHub release page) or
git clone https://github.com/projectacrn/acrn-hypervisor cd acrn-hypervisor git checkout v3.0
The project’s online technical documentation is also tagged to correspond with a specific release: generated v3.0 documents can be found at https://projectacrn.github.io/3.0/. Documentation for the latest development branch is found at https://projectacrn.github.io/latest/.
ACRN v3.0 requires Ubuntu 20.04. Follow the instructions in the Getting Started Guide to get started with ACRN.
What’s New in v3.0¶
- Redesigned ACRN Configuration
We heard your feedback: ACRN configuration is difficult, confusing, and had too many parameters that were not easy to understand. Release v3.0 features a new ACRN Configurator UI tool with a more intuitive design and workflow that simplifies getting the setup for the ACRN hypervisor right. You’ll also see changes for configuring individual VMs. We’ve greatly reduced the number of parameters needing your attention, organized them into basic and advanced categories, provided practical defaults, and added error checking so you can be much more confident in your configuration before building ACRN. We’ve also integrated the previously separated scenario and launch options into a merged scenario XML configuration file managed by the new Configurator. Read more in the ACRN Configurator Tool page.
This is our first major step of continued ACRN user experience improvements. If you have feedback on this, or other aspects of ACRN, please share them on the ACRN users mailing list.
We’ve also simplified installation of the Configurator by providing a Debian package that you can download from the ACRN v3.0 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.0 Board Inspector has improved scanning and provides more messages about potential issues or limitations of your target system that could impact ACRN configuration options. Read more in Board Inspector Tool.
- Commercial off-the-shelf Tiger Lake machine support
The Vecow SPC-7100 system is validated and supported by ACRN. This is a commercially available 11th Generation Intel® Core™ Processor (codenamed Tiger Lake) from Vecow. Read more in the Supported Hardware documentation.
- Refined shutdown & reset sequence
A Windows User VM can now shut down or reset the system gracefully. This supports a user model where a Windows-based VM provides a system management interface. This shutdown capability is achieved by lifecycle managers in each VM that talk to each other via a virtual UART channel.
- Hypervisor Real Time Clock (RTC)
Each VM now has its own PC/AT-compatible RTC/CMOS device emulated by the hypervisor. With this, we can avoid any sudden jump in a VM’s system clock that may confuse certain applications.
- ACRN Debianization
We appreciate a big contribution from the ACRN community! Helmut Buchsbaum from TTTech Industrial submitted a “debianization” feature that lets developers build and package ACRN into several Debian packages, install them on the target Ubuntu or Debian OS, and reboot the machine with ACRN running. Read more in debian/README.rst.
Upgrading to v3.0 from Previous Releases¶
With the introduction of the Configurator UI tool, the need for manually editing XML files is gone. While working on this improved Configurator, we’ve also made many adjustments to available options in the underlying XML files, including merging the previous scenario and launch XML files into a combined scenario XML file. The board XML file generated by the v3.0 Board Inspector tool includes more information about the target system that is needed by the v3.0 Configurator.
We recommend you generate a new board XML for your target system with the v3.0 Board Inspector. You should also use the v3.0 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.0 ACRN hypervisor build process and could produce unexpected errors during the build.
Given the scope of changes for the v3.0 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.0-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.0 build system.
Use the upgrade tool to attempt upgrading configuration files that worked with a release before v3.0. 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.0. This is not our recommended approach.
Here are some additional details about upgrading to the v3.0 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.0 adds the following information to the board XML file for supporting new features and fixes:
--add-llc-catto Board Inspector command line options to manually provide Cache Allocation Technology (CAT) to the generated board XML when the target hardware does not report availability of this feature. See Board Inspector Command-Line Options and PR #7331.
Collect all information about SR-IOV devices: see PR #7302.
Extract all serial TTYs and virtio input devices: see PR #7219.
Extract common ioapic information such as ioapic id, address, gsi base, and gsi num: see PR #6987.
Add another level of die node even though the hardware reports die topology in CPUID: see PR #7080.
Bring up all cores online so Board Inspector can run cpuid to extract all available cores’ information: see PR #7120.
Add CPU capability and BIOS invalid setting checks: see PR #7216.
Improve Board Inspector summary and logging based on log levels option: see PR #7429.
See the Board Inspector Tool documentation for a complete list of steps to install and run the tool.
Update Configuration Options¶
In v3.0, data in a launch XML are now merged into the scenario XML for the new Configurator. When practical, we recommend generating a new scenario and launch scripts by using the Configurator.
As explained in this Upgrading ACRN Configurations to Recent Releases document, we do provide a tool that can assist upgrading your existing pre-v3.0 scenario and launch XML files in the new merged v3.0 format. From there, you can use the v3.0 ACRN Configurator to open 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:
The following elements are added to scenario XML files.
The following elements were removed.
See the Scenario Configuration Options documentation for details about all the available configuration options in the new Configurator.
In v3.0, we refine the structure of the generated scripts so that PCI functions
are identified only by their BDF. This change serves as a mandatory step to align
how passthrough devices are configured for pre-launched and post-launched VMs.
This allows us to present a unified view in the ACRN Configurator for
assigning passthrough device. We removed some obsolete dynamic parameters and updated the
usage of the Device Model (
--cpu_affinity parameter in launch script generation logic to use the lapic ID
instead of pCPU ID. See Device Model Parameters and Launch Script for details.
With the introduction of the improved Configurator, we could improve our Getting Started Guide documentation and let you quickly build a simple ACRN hypervisor and User VM configuration from scratch instead of using a contrived pre-defined scenario configuration. That also let us reorganize and change configuration option documentation to use the newly defined developer-friendly names for configuration options.
Check out our improved Getting Started and Configuration documents:
Here are some of the high-level design documents that were updated since the v2.7 release:
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.0 release (in the latest documentation).
Some obsolete documents were removed from the v3.0 documentation, but can still be found in the archived versions of previous release documentation, such as for v2.7.
Fixed Issues Details¶
7712 - [config_tool] Make Basic tab the default view
7657 - [acrn-configuration-tool] Failed to build acrn with make BOARD=xx SCENARIO=shared RELEASE=y
7641 - config-tools: No launch scripts is generated when clicking save
7637 - config-tools: vsock refine
7634 - [DX][TeamFooding][ADL-S] Failed to build acrn when disable multiboot2 in configurator
7623 - [config_tool] igd-vf para is no longer needed in launch script
7609 - [Config-Tool][UI]build acrn failed after delete VMs via UI
7606 - uninitialized variables are used in hpet.c
7597 - [config_tool] Use Different Board - delete old board file
7592 - [acrn-configuration-tool] Hide PCI option for Console virtual UART type
7581 - [ADL-S][shared]The SOS cmdline parameter shouldn’t be added manually and should be changed in Debian package.
7571 - [config_tool] Working folder with my_board.xml behavior
7563 - [ADL-S][SSRAM]RTCM Unit run failed with 2G memory size
7556 - [config_tool] VUART is configured to PCI and generate launch script without relevant parameters
7546 - [acrn-configuration-tool]Scenario files generated with acrn-configurator for boards without serial ports ACRN debug build fails
7540 - [config_tool]: rename virtio console as virtio serial port(as console)
7538 - configurator: CPU Affinity should be hidden from service vm
7535 - config-tools: add vhost vsock in v3.0
7532 - [config_tool] dialog box and deleting VM related issues
7530 - [configurator] Maximum Virtual CLOS configuration value should not allow negative numbers
7526 - [configurator] Assigning one cpu to multiple Pre-launched VMs is not reported as error
7519 - [config_tool] Duplicate VM name
7514 - fix FEATURES to restore basic view
7506 - config-tools: configurator widget vuart connection needs validation
7500 - [config_tool] Failed to delete post-launched VM due to IVSHMEM
7498 - board_inspector.py fails to run on target with clean Ubuntu installation
7495 - [config_tool] Starting new configuration deletes all files in existing working folder
7492 - configurator: fix configurator build issue
7488 - Configurator version confusion
7486 - [config_tool] Duplicate VM name
7484 - configurator: User-input working directory not working
7481 - [config_tool] No validation for required fields in widgets
7470 - [config_tool][UI] scenario.xml is still generated even though there are setting errors
7469 - [config_tool][UI] No promption on save button if there are wrong settings
7455 - configurator: vUART widget not working
7450 - config-tools: bugfix for file related issues in UI
7445 - [Config-Tool][UI]The shared VMs_name for IVSHMEM is not consistent with the VM_name modification
7442 - [config_tool] Tooltip runs off screen
7435 - configurator: Steps should be inactive until prior step complete
7425 - Cache was not locked after post-RTVM power off and restart
7424 - [config_tool] Virtual USB HCI should be a dropdown menu
7421 - configurator: Unable to display PCI devices droplist
7420 - configurator: Unable to set physical CPU affinity
7419 - configurator: prelaunched VM assigned wrong VMID
7418 - configurator: open folder path incorrect
7413 - config-tools: bugfix for UI
7402 - [acrn-deb] install board_inspector overwrites grub cmdline
7401 - Post-RTVM boot failure with SSRAM enabled
7400 - [acrn-configuration-tool][acrn-deb] grub is not update correctly after install the acrn-deb
7392 - There is no virtio_devices node in generic scenario xml
7383 - [acrn-configuration tool] make scenario shared file error cp error
7376 - Virtio-GPU in guest_vm fails to get the EDID
7370 - [acrn-deb] install_compile_package function is not consistent with gsg
7366 - [acrn-configuration tool] make scenario shared file error cp error
7365 - [config_tool] Get errors running board_inspector
7361 - config_tool: Add check for RTVM pCPU assignment
7356 - [UI] Board info not updated when user changed the board XML
7349 - [UI]Not delete all VMs while delete Service_VM on UI
7345 - Build will fail when using absolute path
7337 - Memory leak after creating udmabuf for virtio-gpu zero_copy
7330 - [PCI UART] Fail to build hypervisor without pci uart bdf value
7327 - refine pgentry_present field in struct pgtable
7301 - [Virtio-GPU]Not enough free memory reserved in SOS
7298 - boot time issue for acrn-dm
7297 - update parameter in schema
7296 - Segment fault is triggered in course of Virtio-gpu rebooting test
7270 - combined cpu_affinity warning for service vm
7267 - service vm cpu affinity issue
7265 - About 20s after booting uaag with usb mediator,usb disk isn’t recognized
7261 - Hide PTM in Configurator UI
7256 - Remove SCHED_IORR and KERNEL_RAWIMAGE
7249 - doc: Exception in Sphinx processing doesn’t display error message
7248 - restore copyright notice of original author of some files.
7246 - Can’t fully parse the xml content that was saved by the same version configurator
7241 - need copyright notice and license in virtio_gpu.c
7212 - Exception”not enough space in guest VE820 SSRAM area” showed when built ACRN with RTCT table
7208 - iasl segfault when reboot user VM with virtio-i2c devices
7197 - The error message is found after adding the specific mac address in the launch script
7172 - [acrn-configuration-tool] offline_cpus won’t be executed in NOOP mode
7171 - Link to instead of including old release notes in the current release
7159 - acrn-config: config tool get_node apic_id failed
7136 - [acrn-configuration-tool] Share memory should never support 512M since the HV_RAM_SIZE_MAX is limited to 0x40000000 but not a platform specific problem
7133 - Guest VM system reset may fail and ACRN DM program hang
7127 - config-tools: remove SERIAL_CONSOLE extracion for bootargs of SOS
7124 - [DM]: Fail to boot the Laag guest if the boot option of “pci=nomsi” is added for Guest kernel
7119 - config-tools: bring all cores online
7109 - Python traceback if the ‘dpkg’ tool is not available
7098 - Memory leakage bug induced by opendir() in ACRN applications
7084 - config_tools: append passthrough gpu bdf in hexadecimal format
7077 - config-tools: find pci hole based on all pci hostbridge
7058 - config_tools: board_inspector cannot generate compliable xml for Qemu
7045 - Segmentation fault when passthrough TSN to post_launched VM with enable_ptm option
7022 - ACRN debian package not complete when source is not cloned to standard folder
7018 - No expected exception generated on some platform.