From 603780e6ef998f9b52ed3ffc942fbeb0a0ad2536 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Tue, 2 Nov 2021 13:45:06 -0700 Subject: [PATCH] doc: draft release notes for v2.7 Start documenting the major changes to v2.7, in particular the UOS/SOS term changes that impact the APIs and documentation, and the scenario name changes. Signed-off-by: David B. Kinder --- doc/release_notes/release_notes_2.7.rst | 149 ++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 doc/release_notes/release_notes_2.7.rst diff --git a/doc/release_notes/release_notes_2.7.rst b/doc/release_notes/release_notes_2.7.rst new file mode 100644 index 000000000..433bb586e --- /dev/null +++ b/doc/release_notes/release_notes_2.7.rst @@ -0,0 +1,149 @@ +.. _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 +`_) 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 +************ +