253 lines
13 KiB
ReStructuredText
253 lines
13 KiB
ReStructuredText
.. _release_notes_3.1:
|
|
|
|
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
|
|
:ref:`introduction` 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
|
|
<https://github.com/projectacrn/acrn-hypervisor/releases/tag/v3.1>`_) 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
|
|
:ref:`gsg` 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
|
|
:ref:`acrn_configurator_tool` and :ref:`scenario-config-options` documents.
|
|
|
|
If you have feedback on this, or other aspects of ACRN, please share them on
|
|
the `ACRN users mailing list <https://lists.projectacrn.org/g/acrn-users>`_.
|
|
|
|
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
|
|
<https://github.com/projectacrn/acrn-hypervisor/releases/download/v3.1/acrn-configurator-3.1.deb>`_
|
|
and install. See the :ref:`gsg` 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
|
|
:ref:`board_inspector_tool`.
|
|
|
|
Sample Application with Two Post-Launched VMs
|
|
With this v3.1 release, we provide a follow-on :ref:`GSG_sample_app` to the
|
|
:ref:`gsg`. 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
|
|
<https://wiki.linuxfoundation.org/realtime/documentation/howto/tools/cyclictest/start>`__,
|
|
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-hypervisor`` GitHub repo :acrn_file:`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:
|
|
|
|
1. Start fresh from our :ref:`gsg`. 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 :ref:`upgrader tool <upgrading_configuration>` 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
|
|
:ref:`upgrading_configuration` 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
|
|
:ref:`board_inspector_tool` documentation for a complete list of steps to
|
|
install and run the tool.
|
|
|
|
Update Configuration Options
|
|
============================
|
|
|
|
As explained in this :ref:`upgrading_configuration` 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_AC`` is now ``SPLIT_LOCK_DETECTION_ENABLED``.
|
|
* ``ENFORCE_TURNOFF_GP`` is now ``UC_LOCK_DETECTION_ENABLED``.
|
|
* ``MCE_ON_PSC_DISABLED`` is now ``MCE_ON_PSC_ENABLED``.
|
|
|
|
See the :ref:`scenario-config-options` documentation for details about all the
|
|
available configuration options in the new Configurator.
|
|
|
|
|
|
Document Updates
|
|
****************
|
|
|
|
Sample Application User Guide
|
|
The new :ref:`GSG_sample_app` 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 <https://docs.projectacrn.org>`_). Here
|
|
are some of the more significant updates:
|
|
|
|
.. rst-class:: rst-columns2
|
|
|
|
* :ref:`gsg`
|
|
* :ref:`rdt_configuration`
|
|
* :ref:`acrn-dm_parameters-and-launch-script`
|
|
* :ref:`scenario-config-options`
|
|
* :ref:`hv-hypercall`
|
|
* :ref:`hardware`
|
|
* :ref:`cpu_sharing`
|
|
* :ref:`enable-s5`
|
|
* :ref:`using_grub`
|
|
* :ref:`vuart_config`
|
|
* :ref:`acrnshell`
|
|
* :ref:`acrnctl`
|
|
|
|
Fixed Issues Details
|
|
********************
|
|
|
|
.. comment example item
|
|
- :acrn-issue:`5626` - Host Call Trace once detected
|
|
|
|
- :acrn-issue:`8162` - dm: virtio-blk parameter error
|
|
- :acrn-issue:`8125` - [hypercube][ADL]Assertion'0' failed found during hypercube_PIO_SCAN testing
|
|
- :acrn-issue:`8111` - [life_mngr] Sync between SOS and RTVM failed when startup hence life_mngr cannot work
|
|
- :acrn-issue:`7948` - Tiger Lake product with CAT enabled needed
|
|
- :acrn-issue:`8063` - Need to generate config_summary.rst
|
|
- :acrn-issue:`8098` - configurator build has dependency on published release documentation
|
|
- :acrn-issue:`8087` - ACRN Configurator enable RDT and CDP after launch scenario
|
|
- :acrn-issue:`8066` - User VM doesn't have IP if launched by acrnd with virtio-net
|
|
- :acrn-issue:`7563` - [ADL-S][SSRAM]RTCM Unit run failed with 2G memory size
|
|
- :acrn-issue:`8068` - [config_tool] Imported scenarios not populating CAT widget
|
|
- :acrn-issue:`7973` - config-tools: User concern about the progress of generating board.xml and not sure whether need exit after waiting some time.
|
|
- :acrn-issue:`7975` - GSG python package xmlschema/elementpath incompatibility
|
|
- :acrn-issue:`8050` - config_tools: cpu affinity
|
|
- :acrn-issue:`8051` - ADL-S][S5]Can't shutdown WaaG with user VM name same as in launch script
|
|
- :acrn-issue:`8046` - [config_tool] Configurator creates duplicate VM name
|
|
- :acrn-issue:`8018` - config-tools: default value & MAX_PCI_BUS_NUM
|
|
- :acrn-issue:`7991` - [Workshop] Configurator create scenario popup window disappear sometimes.
|
|
- :acrn-issue:`8033` - [config_tool] vUART widget address for pre-launched VM doesn't update or display error
|
|
- :acrn-issue:`8000` - [config_tool] Real-time vCPU checkbox is confusing to users
|
|
- :acrn-issue:`7898` - [config_tool] Warning message when users attempt to create a new scenario or import an existing scenario for an existing configuration
|
|
- :acrn-issue:`5692` - Keep Open: Used when updating config option documentation in .xsd files
|
|
- :acrn-issue:`7914` - [config_tool] Focus change to new VM when added
|
|
- :acrn-issue:`7661` - config-tools: Change MCE AC and UC (GP) to enable
|
|
- :acrn-issue:`7927` - [acrn-configuration-tool] ACRN-Configurator does not consider L3 CAT config when opening an exiting configuration
|
|
- :acrn-issue:`7958` - [configurator] Need highlight success or fail status in the popup window of save scenario button
|
|
- :acrn-issue:`7913` - config-tools: build acrn successfully even set the same memory address between the pre vm 0 and hv
|
|
- :acrn-issue:`7931` - Improve HV console as a bash-like one
|
|
- :acrn-issue:`7960` - dm cannot stop correctly
|
|
- :acrn-issue:`7935` - Build EFI-Stub fail
|
|
- :acrn-issue:`7921` - [config_tool] Cache widget: Instructions missing for L2-only users
|
|
- :acrn-issue:`7925` - [configurator] invalid virtual bdf in ivshmem could be saved
|
|
- :acrn-issue:`7942` - [config_tool] vUART and IVSHMEM widgets don't generate address
|
|
- :acrn-issue:`7947` - Need optimize user flow to configure SSRAM for pre-launched RTVM
|
|
- :acrn-issue:`7944` - Service VM hang when reboot user VM
|
|
- :acrn-issue:`7940` - DM: add support for iothread
|
|
- :acrn-issue:`7933` - [config_tool] Add tooltips to CPU affinity virtio
|
|
- :acrn-issue:`7926` - [acrn-configuration-tool]Memory warning when build ACRN for WHL
|
|
- :acrn-issue:`7902` - coding style cleanup in pci.c
|
|
- :acrn-issue:`7917` - [config_tool] Order of plus and minus icons is inconsistent
|
|
- :acrn-issue:`7790` - User VM fail to get IP with vhost net
|
|
- :acrn-issue:`7759` - ERROR: LeakSanitizer: detected memory leaks found when run
|
|
- :acrn-issue:`7915` - [config_tool] Duplicate VM error message - add spacing
|
|
- :acrn-issue:`7906` - config-tools: Board inspector crashed when command line is too long in dmesg
|
|
- :acrn-issue:`7907` - RRSBA should be disabled on platform using retpoline if enumerated
|
|
- :acrn-issue:`7897` - [config_tool] Placement of plus icon for virtio
|
|
- :acrn-issue:`7582` - configurator: board name truncated incorrectly
|
|
- :acrn-issue:`7707` - configurator: IVSHMEM region name lacks pattern check
|
|
- :acrn-issue:`7886` - config-tools: need to hide the 'update-pciids: download failed' message
|
|
- :acrn-issue:`7559` - Copyright year range in code headers is not up to date
|
|
- :acrn-issue:`7884` - config_tool: Move "BIOS Revision" line in Configurator UI
|
|
- :acrn-issue:`7893` - [config_tool] Incompatibility with latest elementpath library
|
|
- :acrn-issue:`7887` - hv: Surges of external interrupts may cause guest hang
|
|
- :acrn-issue:`7880` - fail to run acrn-dm with wrong iasl path
|
|
|
|
Known Issues
|
|
************
|
|
|
|
- :acrn-issue:`6631` - [KATA] Kata support is broken since v2.7
|
|
- :acrn-issue:`6978` - openstack failed since ACRN v2.7
|
|
- :acrn-issue:`7827` - [Configurator] Pre_launched standard VMs cannot share CPU with Service VM
|
|
- :acrn-issue:`8202` - [HV][qemu0][v3.1]HV fail to boot acrn on qemu
|
|
|