acrn-hypervisor/doc/release_notes/release_notes_3.1.rst

.. _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.  Read more in :ref:`board_inspector_tool`.

.. _Vecow SPC-7100:
   https://marketplace.intel.com/s/offering/a5b3b000000PReMAAW/vecow-spc7100-series-11th-gen-intel-core-i7i5i3-processor-ultracompact-f

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 |reg| Core |trade|  Processor (codenamed Tiger
  Lake) from Vecow. Read more in the :ref:`hardware` documentation.

Sample Application
  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`.

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.  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:`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>`_).

* <TO DO: doc list>


Fixed Issues Details
********************

.. comment example item
   - :acrn-issue:`5626` - Host Call Trace once detected


Known Issues
************