.. _release_notes_2.7:

ACRN v2.7 (DRAFT)
#################

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

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

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

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

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


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

API and Documentation Updates for User VM and Service VM Terminology
   More often than not, the terms "UOS" and "SOS" referred to the User VM and
   Service VM components of an ACRN Hypervisor system and not to the VM's OS.
   We've updated the hypervisor APIs and documentation to properly reflect these
   names and removed uses of UOS and SOS.

   In the code, uses of ``uos`` and ``sos`` in names were changed to ``user_vm``
   and ``service_vm`` respectively.  When specifically referring to the OS of
   these VMs, we now use ``user_vm_os`` and ``service_vm_os``. These changes
   appear throughout the C files, as well as in the ``.xml`` configuration
   files.

   For example, here are examples of old and new names:

   .. list-table::
      :widths: 1 1
      :header-rows: 1

      * - Old Name
        - New Name

      * - ``#define SOS_SOCKET_PORT 0x2000``
        - ``#define SERVICE_VM_SOCKET_PORT 0x2000``

      * - ``pkt->uos_active``
        - ``pkt->user_vm_active``

      * - ``static uint16_t get_uos_count(void)``
        - ``static uint16_t get_user_vm_count(void)``

      * - ``static uint16_t get_phy_addr(uint8_t uos_id, uint16_t vaddr)``
        - ``static uint16_t get_phy_addr(uint8_t user_vmid, uint16_t vaddr)``

Update Scenario Names
   The pre-defined scenario names were changed to be indicative of their
   properties instead of an example use.  The "industry" scenario is now called
   "shared", the "logical partitioning" scenario is now called "partitioned",
   and the "hybrid" scenario name remains the same.

   Here are the three configuration scenarios:

   * **Shared**: The physical hardware resources can be shared among
     post-launched User VMs. The Service VM (Device Model) provides device
     emulation for the shared virtual devices.
   * **Partitioned**: The physical resources are strictly dedicated to
     individual pre-launched User VMs and there is no Service VM needed.
   * **Hybrid**: The physical resource are dedicated to pre-launched User
     VMs and the Service VM provides resource emulation and sharing for
     post-launched User VMs, all in the same system configuration.

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

We highly recommended that you follow these instructions to
upgrade to v2.7 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.7 adds
the following hardware information to board XMLs to support new features and
fixes.

  - list features here

The new board XML can be generated using the ACRN board inspector in the same
way as ACRN v2.6. Refer to :ref:`acrn_config_workflow` for a complete list of
steps to deploy and run the tool.

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

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

- list elements here

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

We've updated references throughout the documentation to use "Service VM" and
"User VM" instead of "SOS" and "UOS" respectively.

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

.. rst-class:: rst-columns2

* :ref:`hv-device-passthrough`
* :ref:`vt-d-hld`
* :ref:`faq`
* :ref:`gsg`
* :ref:`overview_dev`
* :ref:`hypervisor-make-options`
* :ref:`acrn_configurator_tool`
* :ref:`acrn_on_qemu`
* :ref:`enable_ivshmem`
* :ref:`enable-s5`
* :ref:`using_grub`
* :ref:`using_partition_mode_on_nuc`
* :ref:`acrn-dm_parameters`
* :ref:`acrntrace`

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

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

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