diff --git a/doc/conf.py b/doc/conf.py index 064556f11..1d5b2327c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -46,7 +46,8 @@ extensions = [ # extlinks provides a macro template extlinks = { - 'acrn-issue': ('https://github.com/projectacrn/acrn-hypervisor/issues/%s', '#') + 'acrn-issue': ('https://github.com/projectacrn/acrn-hypervisor/issues/%s', '#'), + 'acrn-pr': ('https://github.com/projectacrn/acrn-hypervisor/pull/%s', '#') } # use intersphinx linking to link to previous version release notes diff --git a/doc/release_notes/release_notes_3.2.rst b/doc/release_notes/release_notes_3.2.rst new file mode 100644 index 000000000..cdb8ef651 --- /dev/null +++ b/doc/release_notes/release_notes_3.2.rst @@ -0,0 +1,188 @@ +.. _release_notes_3.2: + +ACRN v3.2 (Aug 2023) +#################### + +We are pleased to announce the release of the Project ACRN hypervisor +version 3.2. + +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.2 GitHub release page +`_) or +use Git ``clone`` and ``checkout`` commands:: + + git clone https://github.com/projectacrn/acrn-hypervisor + cd acrn-hypervisor + git checkout v3.2 + +The project's online technical documentation is also tagged to +correspond with a specific release: generated v3.2 documents can be +found at https://projectacrn.github.io/3.2/. Documentation for the +latest development branch is found at https://projectacrn.github.io/latest/. + +ACRN v3.2 requires Ubuntu 22.04. Follow the instructions in the +:ref:`gsg` to get started with ACRN. + + +What's New in v3.2 +****************** + +Enabling New Generation Intel® Processors + ACRN v3.2 release now supports 12th Generation Intel® Atom N-Series Processors + (formerly code named Alder Lake N) and 13th Generation Intel® Core™ Mobile and + Desktop Processors (formerly code named Raptor Lake) with real-time SKUs. + +Hypervisor-Managed Processor Performance Policy Controls + The ACRN hypervisor Configurator now provides processor performance policy + control for CPU frequency if the system supports hardware-controlled + performance states (HWP). This ensures that loaded CPUs can run at least at + their guaranteed frequency level. + +New Debianization Solution for ACRN + The v3.2 release provides a standardized approach for ACRN debianization. + We provide an option to build each component as a separate Debian package and + allow users to select the binary to deploy at package installation time. Users + can also reselect the binary by reconfiguring the installed package. + +Service VM Upgraded to use Ubuntu 22.04 + The v3.2 release upgrades the Service VM OS from Ubuntu 20.04 to 22.04. + +Upgrading to v3.2 from Previous Releases +**************************************** + +We recommend you generate a new board XML for your target system with the v3.2 +Board Inspector. You should also use the v3.2 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.2 ACRN hypervisor +build process and could produce unexpected errors during the build. + +Given the scope of changes for the v3.2 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.2-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.2 build system. +#. Use the :ref:`upgrader tool ` to attempt upgrading + your configuration files that worked with prior releases. You'll need the + matched pair of scenario XML and launch XML files from a prior configuration, + and use them to create a new merged scenario XML file. See + :ref:`upgrading_configuration` for details. +#. Manually edit your previous older scenario XML and launch XML files to make them + compatible with v3.2. This is not our recommended approach. + +Here are some additional details about upgrading to the v3.22 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.2 adds the following information to the +board XML file for supporting new features and fixes: + +* Add CPU frequency information. (See :acrn-pr:`8174`) +* Get connected displays and add them as child nodes to a corresponding graphics + card. (See :acrn-pr:`8230`) +* Add bdf information to an ioport serial controller. (See :acrn-pr:`8237`) +* Stop running and report an error if VMD is enabled in the BIOS setting. (See + :acrn-pr:`8328`) +* Report an error if a USB device is unplugged or disconnected while extracting + USB device information. (See :acrn-pr:`8326`) +* Handle PCI functions with an undefined header layout. (See :acrn-pr:`8233`) + +See the :ref:`board_inspector_tool` documentation for a complete list of steps +to install and run the tool. + +Update Configuration Options +============================ + +As explained in this :ref:`upgrading_configuration` document, we do provide a +tool that can assist upgrading your existing pre-v3.2 scenario XML files in the +new merged v3.2 format. From there, you can use the v3.2 ACRN Configurator UI to +open the upgraded scenario file for viewing and further editing if the upgrader +tool lost meaningful data during the conversion. + +The ACRN Configurator adds the following features and fixes to improve the user +experience: + +* Support virtio GPU configuration. (See :acrn-pr:`8248`) +* Determine SSRAM_ENABLED value automatically. (See :acrn-pr:`8232`) +* Add "CPU performance policy type" option. (See :acrn-pr:`8174`) +* Add "exclusively owns physical CPUs" checkbox to pre-launched and + post-launched VMs. (See :acrn-pr:`8290`) +* Generate ``config_summary.rst`` when saving scenario XML and launch scripts. + (See :acrn-pr:`8309`) + +See the :ref:`scenario-config-options` documentation for details about all the +available configuration options in the new Configurator. + + +Document Updates +**************** + +Here are some of the more significant documentation updates from the v3.1 release: + +.. rst-class:: rst-columns2 + +* :ref:`asa` +* :ref:`hld-security` +* :ref:`hv-cpu-virt` +* :ref:`gsg` +* :ref:`GSG_sample_app` +* :ref:`release_notes_3.2` +* :ref:`release_notes_3.0.2` +* :ref:`acrn_configurator_tool` +* :ref:`acrn_doc` +* :ref:`enable_multiple_displays` +* :ref:`acrn-dm_parameters-and-launch-script` +* :ref:`scenario-config-options` + +Fixed Issues Details +******************** + +.. comment example item + - :acrn-issue:`5626` - Host Call Trace once detected + +- :acrn-issue:`8435` - Post-launch RTVM and WaaG running simultaneously will cause Windows kernel crash +- :acrn-issue:`8445` - Fix security vulnerability for configurator dependent library +- :acrn-issue:`8454` - Fail to boot RTVM or UaaG when passthru Ethernet controller +- :acrn-issue:`8448` - The script in Sample Application Guide is not working +- :acrn-issue:`8352` - Sample app fails to build for v3.2 RC1 +- :acrn-issue:`8439` - Possible null pointer dereference/uninitialized variable/buffer overflow in code +- :acrn-issue:`8435` - Post-launch RTVM and WaaG running simultaneously will cause Windows kernel crash +- :acrn-issue:`8432` - Flickering screen when passing ADL-N and RPL-P platforms +- :acrn-issue:`8413` - hypervisor: 'vm_config' may be used uninitialized [-Werror=maybe-uninitialized] +- :acrn-issue:`8382` - Failed to build with gcc 12 +- :acrn-issue:`8422` - Failed to generate config summary and launch scripts if CAT is enabled in configurator +- :acrn-issue:`8395` - Configurator load fails because it needs to download RstCloth packages. +- :acrn-issue:`8380` - Cannot generate XML file for target system +- :acrn-issue:`8388` - Fail to generate board XML because of non-ASCII characters +- :acrn-issue:`8385` - Failed to generate config_summary.rst when board.xml has "module" node under the "processors/die" +- :acrn-issue:`8359` - GSG: change the method of checking kernel version of grub menuentry +- :acrn-issue:`8246` - Debianization improvement +- :acrn-issue:`8344` - debian/debian_build.sh fails when a work folder contains files other than XML +- :acrn-issue:`8111` - Sync between Service VM OS and RTVM failed when startup hence life_mngr cannot work +- :acrn-issue:`8315` - Invoking a command with partial executable path in Board Inspector Python file +- :acrn-issue:`8274` - Wrong kernel cmdline added in grub menu when install acrn-hypervisor + + +Known Issues +************ + +- :acrn-issue:`6631` - Kata support is broken since v2.7 +- :acrn-issue:`6978` - openstack failed since ACRN v2.7 +- :acrn-issue:`7827` - Pre_launched standard VMs cannot share CPU with Service VM in configurator +- :acrn-issue:`8202` - HV fail to boot acrn on QEMU +- :acrn-issue:`8471` - PTM enabling failure on i225 NIC +- :acrn-issue:`8472` - Failed to clear memory for post-launched standard VM +- :acrn-issue:`8473` - Missing VirtIO GPU Windows VF driver +