mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-06-03 12:49:45 +00:00
192 lines
8.0 KiB
ReStructuredText
192 lines
8.0 KiB
ReStructuredText
.. _release_notes_3.1:
|
|
|
|
ACRN v3.1 (Sep 2022) Draft
|
|
##########################
|
|
|
|
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.
|
|
TODO: add reference to tutorial
|
|
|
|
Improved TSC frequency reporting
|
|
The hypervisor now reports 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
|
|
****************************************
|
|
|
|
As with the v3.0 release 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.1 Board Inspector tool includes
|
|
more information about the target system that is needed by the v3.1
|
|
Configurator.
|
|
|
|
We recommend you generate a new board XML for your target system with the v3.1
|
|
Board Inspector and use the v3.1 Configurator to generate a new
|
|
scenario XML file and launch scripts. Board XML and Scenario XML files
|
|
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:`upgrade tool <upgrading_configuration>` to attempt upgrading
|
|
configuration files that worked with a release before v3.1. 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:
|
|
|
|
- <TODO: topic and PR reference>
|
|
|
|
See the :ref:`board_inspector_tool` documentation for a complete list of steps
|
|
to install and run the tool.
|
|
|
|
Update Configuration Options
|
|
============================
|
|
|
|
<TO DO>
|
|
|
|
As part of the developer experience improvements to ACRN configuration, the following XML elements
|
|
were refined in the scenario XML file:
|
|
|
|
- <TO DO>
|
|
|
|
The following elements are added to scenario XML files.
|
|
|
|
- <TO DO>
|
|
|
|
The following elements were removed.
|
|
|
|
- <TO DO>
|
|
|
|
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:`GSG_sample_app`
|
|
* :ref:`rdt_configuration`
|
|
* :ref:`acrn-dm_parameters-and-launch-script`
|
|
* :ref:`scenario-config-options`
|
|
|
|
Fixed Issues Details
|
|
********************
|
|
|
|
.. comment example item
|
|
- :acrn-issue:`5626` - Host Call Trace once detected
|
|
|
|
|
|
Known Issues
|
|
************
|
|
|