acrn-hypervisor/doc/release_notes/release_notes_2.5.rst

.. _release_notes_2.5:

ACRN v2.5 (Jun 2021) DRAFT
##########################

We are pleased to announce the release of the Project ACRN hypervisor
version 2.5.

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 either download this source code as a zip or
tar.gz file (see the `ACRN v2.5 GitHub release page
<https://github.com/projectacrn/acrn-hypervisor/releases/tag/v2.5>`_) or
use Git ``clone`` and ``checkout`` commands::

   git clone https://github.com/projectacrn/acrn-hypervisor
   cd acrn-hypervisor
   git checkout v2.5

The project's online technical documentation is also tagged to
correspond with a specific release: generated v2.5 documents can be
found at https://projectacrn.github.io/2.5/.  Documentation for the
latest under-development branch is found at
https://projectacrn.github.io/latest/.

ACRN v2.5 requires Ubuntu 18.04.  Follow the instructions in the
:ref:`rt_industry_ubuntu_setup` to get started with ACRN.


What's New in v2.5
******************

- A brand-new concept, nested virtualization, is introduced as a preview in this
  v2.5 release. It's designed to leverage KVM/Qemu community's rich feature set
  while keeping ACRN's unique advantages in partition mode and hybrid mode. Read
  more in the :ref:`nested_virt` advanced guide.

- The v2.5 release supports the upcoming 12th generation of Intel |reg| Core |trade|
  processor (codename Alder Lake)

- EFI stub, previously retired in favor of using direct boot, returns as an
  alternative to end-to-end secure boot with Grub. The hypervisor, ServiceVM
  kernel, and prelaunched VM kernel are packaged into a single blob,
  ``acrn.efi``, as an EFI application, which can then be verified together by
  the EFI BIOS. Read more in the
  :ref:`how-to-enable-acrn-secure-boot-with-efi-stub` and
  :ref:`how-to-enable-acrn-secure-boot-with-grub` advanced guides.

- :ref:`ACRN hypervisor modularization <modularity>` has been improved to be more
  scalable, including change to multiboot, interrupt handling, paging and memory
  management, timers, and more.

- The ACRN configuration and build process continues to evolve from the changes
  made in the previous releases.  For instructions using
  the build system, refer to :ref:`getting-started-building`. For an
  introduction on the concepts and workflow of the configuration tools and
  processes, refer to :ref:`acrn_configuration_tool`.


Upgrading to v2.5 From Previous Releases
****************************************

We highly recommended that you follow these instructions to
upgrade to v2.5 from previous ACRN releases.

Generate New Board XML
======================

Board XML files, generated by ACRN board inspector, contain board information
that is essential to build ACRN. Compared to previous versions, ACRN v2.5
extends the schema of board XMLs to summarize board information more
systematically. You must regenerate your board XML file using the new
board inspector when you upgrade to ACRN v2.5 to get the additional information
needed for configuration.

Before using the new board inspector, ensure you have Python >= 3.6 on the target
board and install the ``lxml`` PyPI package. Refer to :ref:`upgrade_python` for
detailed steps to check and upgrade your Python version. The ``lxml`` package can be
installed by executing the following command:

.. code-block:: bash

   sudo pip3 install lxml

.. note::
   Refer to :ref:`acrn_config_workflow` for a complete list of tools required to
   run the board inspector.

With the prerequisites done, copy the entire board inspector folder from
``misc/config_tools/board_inspector`` to the target board, ``cd`` to that
directory on the target, and run the board inspector tool using::

   sudo python3 cli.py <my_board_name>

This will generate ``<my_board_name>.xml`` in the current working directory.
You'll need to copy that XML file back to the host system to continue
development.

Add New Configuration Options
=============================

In v2.5, the following elements are added to scenario XML files:

- :option:`hv.FEATURES.NVMX_ENABLED`
- :option:`vm.PTM`

The following element is renamed:

- :option:`hv.FEATURES.SSRAM.SSRAM_ENABLED` (was ``hv.FEATURES.PSRAM.PSRAM_ENABLED`` in v2.4)

Constraints on values of the following element has changed:

- :option:`vm.guest_flags.guest_flag` no longer accepts an empty text. For VMs
  without any guest flag set, a ``0`` should be given.

Document Updates
****************

With the changes to ACRN configuration noted above, we made updates
to the ACRN documentation around configuration and options:

.. rst-class:: rst-columns2

* :ref:`acrn_configuration_tool`
* :ref:`scenario-config-options`
* :ref:`acrn-dm_parameters`
* :ref:`kernel-parameters`

Some new capabilities are documented here:

* :ref:`nested_virt`
* :ref:`enable-ptm`

We've also made edits throughout the documentation to improve clarity,
formatting, and presentation throughout the ACRN documentation:

.. rst-class:: rst-columns2

* :ref:`contribute_guidelines`
* :ref:`doc_guidelines`
* :ref:`ahci-hld`
* :ref:`hv-device-passthrough`
* :ref:`hv-hypercall`
* :ref:`timer-hld`
* :ref:`l1tf`
* :ref:`modularity`
* :ref:`sw_design_guidelines`
* :ref:`trusty_tee`
* :ref:`getting-started-building`
* :ref:`gsg`
* :ref:`hardware`
* :ref:`acrn_on_qemu`
* :ref:`acrn_doc`
* :ref:`enable_ivshmem`
* :ref:`running_deb_as_serv_vm`
* :ref:`trusty-security-services`
* :ref:`using_hybrid_mode_on_nuc`
* :ref:`connect_serial_port`


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

.. comment example item
   - :acrn-issue:`5626` - [CFL][industry] Host Call Trace once detected

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