1.. _release_notes_3.1: 2 3ACRN v3.1 (Sep 2022) 4#################### 5 6We are pleased to announce the release of the Project ACRN hypervisor 7version 3.1. 8 9ACRN is a flexible, lightweight reference hypervisor that is built with 10real-time and safety-criticality in mind. It is optimized to streamline 11embedded development through an open-source platform. See the 12:ref:`introduction` introduction for more information. 13 14All project ACRN source code is maintained in the 15https://github.com/projectacrn/acrn-hypervisor repository and includes 16folders for the ACRN hypervisor, the ACRN device model, tools, and 17documentation. You can download this source code either as a zip or 18tar.gz file (see the `ACRN v3.1 GitHub release page 19<https://github.com/projectacrn/acrn-hypervisor/releases/tag/v3.1>`_) or 20use Git ``clone`` and ``checkout`` commands:: 21 22 git clone https://github.com/projectacrn/acrn-hypervisor 23 cd acrn-hypervisor 24 git checkout v3.1 25 26The project's online technical documentation is also tagged to 27correspond with a specific release: generated v3.1 documents can be 28found at https://projectacrn.github.io/3.1/. Documentation for the 29latest development branch is found at https://projectacrn.github.io/latest/. 30 31ACRN v3.1 requires Ubuntu 20.04. Follow the instructions in the 32:ref:`gsg` to get started with ACRN. 33 34 35What's New in v3.1 36****************** 37 38More ACRN Configuration Improvements 39 Release v3.0 featured a new ACRN Configurator UI tool with a more intuitive 40 design and workflow that simplifies getting the setup for the ACRN hypervisor 41 right. With this v3.1 release, we've continued making improvements to the 42 Configurator including more comprehensive error checking with more 43 developer-friendly messages. You'll also see additional advanced 44 configuration settings for tuning real-time performance including Cache 45 Allocation Technology (CAT) and vCPU affinity. Read more in the 46 :ref:`acrn_configurator_tool` and :ref:`scenario-config-options` documents. 47 48 If you have feedback on this, or other aspects of ACRN, please share them on 49 the `ACRN users mailing list <https://lists.projectacrn.org/g/acrn-users>`_. 50 51 As with the v3.0 release, we've simplified installation of the Configurator by providing a Debian 52 package that you can download from the `ACRN v3.1 tag assets 53 <https://github.com/projectacrn/acrn-hypervisor/releases/download/v3.1/acrn-configurator-3.1.deb>`_ 54 and install. See the :ref:`gsg` for more information. 55 56Improved Board Inspector Collection and Reporting 57 You run the ACRN Board Inspector tool to collect information about your target 58 system's processors, memory, devices, and more. The generated board XML file 59 is used by the ACRN Configurator to determine which ACRN configuration options 60 are possible, as well as possible values for target system resources. The v3.1 61 Board Inspector has improved scanning and provides more messages about 62 potential issues or limitations of your target system that could impact ACRN 63 configuration options. 64 65 The Board Inspector is updated to probe beyond CPUID 66 information for Cache Allocation Technology (CAT) support and also detects 67 availability of L3 CAT by accessing the CAT MSRs directly. Read more in 68 :ref:`board_inspector_tool`. 69 70Sample Application with Two Post-Launched VMs 71 With this v3.1 release, we provide a follow-on :ref:`GSG_sample_app` to the 72 :ref:`gsg`. This sample application shows how to create two VMs that are 73 launched on your target system running ACRN. One VM is a real-time VM running 74 `cyclictest 75 <https://wiki.linuxfoundation.org/realtime/documentation/howto/tools/cyclictest/start>`__, 76 an open-source application commonly used to measure latencies in real-time 77 systems. This real-time VM (RT_VM) uses inter-VM shared memory (IVSHMEM) to 78 send data to a second Human-Machine Interface VM (HMI_VM) that formats and 79 presents the collected data as a histogram on a web page shown by a browser. 80 This guide shows how to configure, create, and launch the two VM images that 81 make up this application. Full code for the sample application is provided in 82 the ``acrn-hypervisor`` GitHub repo :acrn_file:`misc/sample_application`. 83 84Multiple-Displays Support for VMs 85 The virtio-gpu mechanism is enhanced to support VMs with multiple displays. 86 87Improved TSC Frequency Reporting 88 The hypervisor now reports Time Stamp Counter (TSC) frequency in KHz so that 89 VMs can get that number without calibrating to a high precision timer. 90 91Upgrading to v3.1 from Previous Releases 92**************************************** 93 94We recommend you generate a new board XML for your target system with the v3.1 95Board Inspector. You should also use the v3.1 Configurator to generate a new 96scenario XML file and launch scripts. Scenario XML files and launch scripts 97created by previous ACRN versions will not work with the v3.1 ACRN hypervisor 98build process and could produce unexpected errors during the build. 99 100Given the scope of changes for the v3.1 release, we have recommendations for how 101to upgrade from prior ACRN versions: 102 1031. Start fresh from our :ref:`gsg`. This is the best way to ensure you have a 104 v3.1-ready board XML file from your target system and generate a new scenario 105 XML and launch scripts from the new ACRN Configurator that are consistent and 106 will work for the v3.1 build system. 107#. Use the :ref:`upgrader tool <upgrading_configuration>` to attempt upgrading 108 configuration files that worked with a release before v3.1. You'll need the 109 matched pair of scenario XML and launch XML files from a prior configuration, 110 and use them to create a new merged scenario XML file. See 111 :ref:`upgrading_configuration` for details. 112#. Manually edit your prior scenario XML and launch XML files to make them 113 compatible with v3.1. This is not our recommended approach. 114 115Here are some additional details about upgrading to the v3.1 release. 116 117Generate New Board XML 118====================== 119 120Board XML files, generated by ACRN Board Inspector, contain board information 121that is essential for building the ACRN hypervisor and setting up User VMs. 122Compared to previous versions, ACRN v3.1 adds the following information to the board 123XML file for supporting new features and fixes: 124 125* Probe and detect availability of L3 CAT by accessing the CAT MSRs directly 126* Refactor MSR utilities 127* Record all details from the real-time configuration table (RTCT) in the board 128 XML and generate vRTCT instead of copying a physical one 129 130The v3.1 Board Inspector includes a progress bar and timeout mechanism, as well 131as more developer-friendly logs and error messages. See the 132:ref:`board_inspector_tool` documentation for a complete list of steps to 133install and run the tool. 134 135Update Configuration Options 136============================ 137 138As explained in this :ref:`upgrading_configuration` document, we do provide a 139tool that can assist upgrading your existing pre-v3.1 scenario XML files in the 140new merged v3.1 format. From there, you can use the v3.1 ACRN Configurator to 141open the upgraded scenario file for viewing and further editing if the upgrader 142tool lost meaningful data during the conversion. 143 144As part of the developer experience improvements to ACRN configuration, the 145following XML elements were refined in the scenario XML file: 146 147* ``ENFORCE_TURNOFF_AC`` is now ``SPLIT_LOCK_DETECTION_ENABLED``. 148* ``ENFORCE_TURNOFF_GP`` is now ``UC_LOCK_DETECTION_ENABLED``. 149* ``MCE_ON_PSC_DISABLED`` is now ``MCE_ON_PSC_ENABLED``. 150 151See the :ref:`scenario-config-options` documentation for details about all the 152available configuration options in the new Configurator. 153 154 155Document Updates 156**************** 157 158Sample Application User Guide 159 The new :ref:`GSG_sample_app` documentation shows how to configure, build, and 160 run a practical application with a Real-Time VM and Human-Machine Interface 161 VM that communicate using inter-VM shared memory. 162 163 164We've also made edits throughout the documentation to improve clarity, 165formatting, and presentation. We started updating feature enabling tutorials 166based on the new Configurator, and will continue updating them after the v3.1 167release (in the `latest documentation <https://docs.projectacrn.org>`_). Here 168are some of the more significant updates: 169 170.. rst-class:: rst-columns2 171 172* :ref:`gsg` 173* :ref:`rdt_configuration` 174* :ref:`acrn-dm_parameters-and-launch-script` 175* :ref:`scenario-config-options` 176* :ref:`hv-hypercall` 177* :ref:`hardware` 178* :ref:`cpu_sharing` 179* :ref:`enable-s5` 180* :ref:`using_grub` 181* :ref:`vuart_config` 182* :ref:`acrnshell` 183* :ref:`acrnctl` 184 185Fixed Issues Details 186******************** 187 188.. comment example item 189 - :acrn-issue:`5626` - Host Call Trace once detected 190 191- :acrn-issue:`8162` - dm: virtio-blk parameter error 192- :acrn-issue:`8125` - [hypercube][ADL]Assertion'0' failed found during hypercube_PIO_SCAN testing 193- :acrn-issue:`8111` - [life_mngr] Sync between SOS and RTVM failed when startup hence life_mngr cannot work 194- :acrn-issue:`7948` - Tiger Lake product with CAT enabled needed 195- :acrn-issue:`8063` - Need to generate config_summary.rst 196- :acrn-issue:`8098` - configurator build has dependency on published release documentation 197- :acrn-issue:`8087` - ACRN Configurator enable RDT and CDP after launch scenario 198- :acrn-issue:`8066` - User VM doesn't have IP if launched by acrnd with virtio-net 199- :acrn-issue:`7563` - [ADL-S][SSRAM]RTCM Unit run failed with 2G memory size 200- :acrn-issue:`8068` - [config_tool] Imported scenarios not populating CAT widget 201- :acrn-issue:`7973` - config-tools: User concern about the progress of generating board.xml and not sure whether need exit after waiting some time. 202- :acrn-issue:`7975` - GSG python package xmlschema/elementpath incompatibility 203- :acrn-issue:`8050` - config_tools: cpu affinity 204- :acrn-issue:`8051` - ADL-S][S5]Can't shutdown WaaG with user VM name same as in launch script 205- :acrn-issue:`8046` - [config_tool] Configurator creates duplicate VM name 206- :acrn-issue:`8018` - config-tools: default value & MAX_PCI_BUS_NUM 207- :acrn-issue:`7991` - [Workshop] Configurator create scenario popup window disappear sometimes. 208- :acrn-issue:`8033` - [config_tool] vUART widget address for pre-launched VM doesn't update or display error 209- :acrn-issue:`8000` - [config_tool] Real-time vCPU checkbox is confusing to users 210- :acrn-issue:`7898` - [config_tool] Warning message when users attempt to create a new scenario or import an existing scenario for an existing configuration 211- :acrn-issue:`5692` - Keep Open: Used when updating config option documentation in .xsd files 212- :acrn-issue:`7914` - [config_tool] Focus change to new VM when added 213- :acrn-issue:`7661` - config-tools: Change MCE AC and UC (GP) to enable 214- :acrn-issue:`7927` - [acrn-configuration-tool] ACRN-Configurator does not consider L3 CAT config when opening an exiting configuration 215- :acrn-issue:`7958` - [configurator] Need highlight success or fail status in the popup window of save scenario button 216- :acrn-issue:`7913` - config-tools: build acrn successfully even set the same memory address between the pre vm 0 and hv 217- :acrn-issue:`7931` - Improve HV console as a bash-like one 218- :acrn-issue:`7960` - dm cannot stop correctly 219- :acrn-issue:`7935` - Build EFI-Stub fail 220- :acrn-issue:`7921` - [config_tool] Cache widget: Instructions missing for L2-only users 221- :acrn-issue:`7925` - [configurator] invalid virtual bdf in ivshmem could be saved 222- :acrn-issue:`7942` - [config_tool] vUART and IVSHMEM widgets don't generate address 223- :acrn-issue:`7947` - Need optimize user flow to configure SSRAM for pre-launched RTVM 224- :acrn-issue:`7944` - Service VM hang when reboot user VM 225- :acrn-issue:`7940` - DM: add support for iothread 226- :acrn-issue:`7933` - [config_tool] Add tooltips to CPU affinity virtio 227- :acrn-issue:`7926` - [acrn-configuration-tool]Memory warning when build ACRN for WHL 228- :acrn-issue:`7902` - coding style cleanup in pci.c 229- :acrn-issue:`7917` - [config_tool] Order of plus and minus icons is inconsistent 230- :acrn-issue:`7790` - User VM fail to get IP with vhost net 231- :acrn-issue:`7759` - ERROR: LeakSanitizer: detected memory leaks found when run 232- :acrn-issue:`7915` - [config_tool] Duplicate VM error message - add spacing 233- :acrn-issue:`7906` - config-tools: Board inspector crashed when command line is too long in dmesg 234- :acrn-issue:`7907` - RRSBA should be disabled on platform using retpoline if enumerated 235- :acrn-issue:`7897` - [config_tool] Placement of plus icon for virtio 236- :acrn-issue:`7582` - configurator: board name truncated incorrectly 237- :acrn-issue:`7707` - configurator: IVSHMEM region name lacks pattern check 238- :acrn-issue:`7886` - config-tools: need to hide the 'update-pciids: download failed' message 239- :acrn-issue:`7559` - Copyright year range in code headers is not up to date 240- :acrn-issue:`7884` - config_tool: Move "BIOS Revision" line in Configurator UI 241- :acrn-issue:`7893` - [config_tool] Incompatibility with latest elementpath library 242- :acrn-issue:`7887` - hv: Surges of external interrupts may cause guest hang 243- :acrn-issue:`7880` - fail to run acrn-dm with wrong iasl path 244 245Known Issues 246************ 247 248- :acrn-issue:`6631` - [KATA] Kata support is broken since v2.7 249- :acrn-issue:`6978` - openstack failed since ACRN v2.7 250- :acrn-issue:`7827` - [Configurator] Pre_launched standard VMs cannot share CPU with Service VM 251- :acrn-issue:`8202` - [HV][qemu0][v3.1]HV fail to boot acrn on qemu 252 253