diff --git a/doc/release_notes/release_notes_3.1.rst b/doc/release_notes/release_notes_3.1.rst new file mode 100644 index 000000000..28ecb1d4d --- /dev/null +++ b/doc/release_notes/release_notes_3.1.rst @@ -0,0 +1,180 @@ +.. _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 +`_) 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 `_. + + 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 + `_ + 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 + `__, + 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 ` 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: + + - + +See the :ref:`board_inspector_tool` documentation for a complete list of steps +to install and run the tool. + +Update Configuration Options +============================ + + + +As part of the developer experience improvements to ACRN configuration, the following XML elements +were refined in the scenario XML file: + +- + +The following elements are added to scenario XML files. + +- + +The following elements were removed. + +- + +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 `_). + +* + + +Fixed Issues Details +******************** + +.. comment example item + - :acrn-issue:`5626` - Host Call Trace once detected + + +Known Issues +************ +