.. _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 ************