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

.. _release_notes_3.2:

ACRN v3.2 (Aug 2023)
####################

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

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.2 GitHub release page
<https://github.com/projectacrn/acrn-hypervisor/releases/tag/v3.2>`_) or
use Git ``clone`` and ``checkout`` commands::

   git clone https://github.com/projectacrn/acrn-hypervisor
   cd acrn-hypervisor
   git checkout v3.2

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

ACRN v3.2 requires Ubuntu 22.04.  Follow the instructions in the
:ref:`gsg` to get started with ACRN.


What's New in v3.2
******************

Enabling New Generation Intel® Processors
  ACRN v3.2 release now supports 12th Generation Intel® Atom N-Series Processors
  (formerly code named Alder Lake N) and 13th Generation Intel® Core™ Mobile and
  Desktop Processors (formerly code named Raptor Lake) with real-time SKUs.

Hypervisor-Managed Processor Performance Policy Controls
  The ACRN hypervisor Configurator now provides processor performance policy
  control for CPU frequency if the system supports hardware-controlled
  performance states (HWP). This ensures that loaded CPUs can run at least at
  their guaranteed frequency level.

New Debianization Solution for ACRN
  The v3.2 release provides a standardized approach for ACRN debianization.
  We provide an option to build each component as a separate Debian package and
  allow users to select the binary to deploy at package installation time. Users
  can also reselect the binary by reconfiguring the installed package.

Service VM Upgraded to use Ubuntu 22.04
  The v3.2 release upgrades the Service VM OS from Ubuntu 20.04 to 22.04.

Upgrading to v3.2 from Previous Releases
****************************************

We recommend you generate a new board XML for your target system with the v3.2
Board Inspector. You should also use the v3.2 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.2 ACRN hypervisor
build process and could produce unexpected errors during the build.

Given the scope of changes for the v3.2 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.2-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.2 build system.
#. Use the :ref:`upgrader tool <upgrading_configuration>` to attempt upgrading
   your configuration files that worked with prior releases. 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 previous older scenario XML and launch XML files to make them
   compatible with v3.2.  This is not our recommended approach.

Here are some additional details about upgrading to the v3.2 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.2 adds the following information to the
board XML file for supporting new features and fixes:

* Add CPU frequency information. (See :acrn-pr:`8174`)
* Get connected displays and add them as child nodes to a corresponding graphics
  card. (See :acrn-pr:`8230`)
* Add bdf information to an ioport serial controller. (See :acrn-pr:`8237`)
* Stop running and report an error if VMD is enabled in the BIOS setting. (See
  :acrn-pr:`8328`)
* Report an error if a USB device is unplugged or disconnected while extracting
  USB device information. (See :acrn-pr:`8326`)
* Handle PCI functions with an undefined header layout. (See :acrn-pr:`8233`)

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.2 scenario XML files in the
new merged v3.2 format. From there, you can use the v3.2 ACRN Configurator UI to
open the upgraded scenario file for viewing and further editing if the upgrader
tool lost meaningful data during the conversion.

The ACRN Configurator adds the following features and fixes to improve the user
experience:

* Support virtio GPU configuration. (See :acrn-pr:`8248`)
* Determine SSRAM_ENABLED value automatically. (See :acrn-pr:`8232`)
* Add "CPU performance policy type" option. (See :acrn-pr:`8174`)
* Add "exclusively owns physical CPUs" checkbox to pre-launched and
  post-launched VMs. (See :acrn-pr:`8290`)
* Generate ``config_summary.rst`` when saving scenario XML and launch scripts.
  (See :acrn-pr:`8309`)

See the :ref:`scenario-config-options` documentation for details about all the
available configuration options in the new Configurator.


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

Here are some of the more significant documentation updates from the v3.1 release:

.. rst-class:: rst-columns2

* :ref:`asa`
* :ref:`hld-security`
* :ref:`hv-cpu-virt`
* :ref:`gsg`
* :ref:`GSG_sample_app`
* :ref:`release_notes_3.2`
* :ref:`release_notes_3.0.2`
* :ref:`acrn_configurator_tool`
* :ref:`acrn_doc`
* :ref:`enable_multiple_displays`
* :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

- :acrn-issue:`8435` - Post-launch RTVM and WaaG running simultaneously will cause Windows kernel crash
- :acrn-issue:`8445` - Fix security vulnerability for configurator dependent library
- :acrn-issue:`8454` - Fail to boot RTVM or UaaG when passthru Ethernet controller
- :acrn-issue:`8448` - The script in Sample Application Guide is not working
- :acrn-issue:`8352` - Sample app fails to build for v3.2 RC1
- :acrn-issue:`8439` - Possible null pointer dereference/uninitialized variable/buffer overflow in code
- :acrn-issue:`8435` - Post-launch RTVM and WaaG running simultaneously will cause Windows kernel crash
- :acrn-issue:`8432` - Flickering screen when passing ADL-N and RPL-P platforms
- :acrn-issue:`8413` - hypervisor: 'vm_config' may be used uninitialized [-Werror=maybe-uninitialized]
- :acrn-issue:`8382` - Failed to build with gcc 12
- :acrn-issue:`8422` - Failed to generate config summary and launch scripts if CAT is enabled in configurator
- :acrn-issue:`8395` - Configurator load fails because it needs to download RstCloth packages.
- :acrn-issue:`8380` - Cannot generate XML file for target system
- :acrn-issue:`8388` - Fail to generate board XML because of non-ASCII characters
- :acrn-issue:`8385` - Failed to generate config_summary.rst when board.xml has "module" node under the "processors/die"
- :acrn-issue:`8359` - GSG: change the method of checking kernel version of grub menuentry
- :acrn-issue:`8246` - Debianization improvement
- :acrn-issue:`8344` - debian/debian_build.sh fails when a work folder contains files other than XML
- :acrn-issue:`8111` - Sync between Service VM OS and RTVM failed when startup hence life_mngr cannot work
- :acrn-issue:`8315` - Invoking a command with partial executable path in Board Inspector Python file
- :acrn-issue:`8274` - Wrong kernel cmdline added in grub menu when install acrn-hypervisor


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

- :acrn-issue:`6631` - Kata support is broken since v2.7
- :acrn-issue:`6978` - openstack failed since ACRN v2.7
- :acrn-issue:`7827` - Pre_launched standard VMs cannot share CPU with Service VM in configurator
- :acrn-issue:`8202` - HV fail to boot acrn on QEMU
- :acrn-issue:`8471` - PTM enabling failure on i225 NIC
- :acrn-issue:`8472` - Failed to clear memory for post-launched standard VM
- :acrn-issue:`8473` - Missing VirtIO GPU Windows VF driver