diff --git a/doc/release_notes/release_notes_2.4.rst b/doc/release_notes/release_notes_2.4.rst index d5afa6e38..cae966e49 100644 --- a/doc/release_notes/release_notes_2.4.rst +++ b/doc/release_notes/release_notes_2.4.rst @@ -3,12 +3,12 @@ ACRN v2.4 (Mar 2021) - DRAFT ############################ -We are pleased to announce the release of the Project ACRN -hypervisor version 2.4. +We are pleased to announce the release of the Project ACRN hypervisor +version 2.4. 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. Check out the +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 @@ -16,7 +16,7 @@ folders for the ACRN hypervisor, the ACRN device model, tools, and documentation. You can either download this source code as a zip or tar.gz file (see the `ACRN v2.4 GitHub release page `_) or -use Git clone and checkout commands:: +use the Git ``clone`` and ``checkout`` commands:: git clone https://github.com/projectacrn/acrn-hypervisor cd acrn-hypervisor @@ -38,9 +38,190 @@ What's New in v2.4 ACRN Configuration and Build ============================ -[Add a short description of the changes to the ACRN configuration and build -process that no longer uses Kconfig and relies on XML files, and refer them to -the updated building from source and configuration options documents] +The following major changes on ACRN configuration and build process have been +integrated into v2.4: + + - Metadata of configuration entries, including documentation and attributes, + has been removed from ``scenario`` XMLs. + - The C sources generated from ``board`` and ``scenario`` XMLs are no longer + maintained in the repository. Instead they'll be generated as part of the + hypervisor build. Users can now find them under ``configs/`` of the build + directory. + - Kconfig is no longer used for configuration. Related build targets, such as + ``defconfig``, now apply to the configuration files in XML. + - The ``make`` command-line variables ``BOARD`` and ``BOARD_FILE`` have been + unified. Users can now specify ``BOARD=xxx`` when invoking ``make`` with + ``xxx`` being either a board name or a (relative or absolute) path to a + board XML. ``SCENARIO`` and ``SCENARIO_FILE`` have been unified in the same + way. + +For complete instructions to get started with the new build system, refer to +:ref:`getting-started-building`. For an introduction on the concepts and +workflow of the new configuration mechanism, refer to +:ref:`acrn_configuration_tool`. + +Upgrading to v2.4 From Previous Releases +**************************************** + +Users are highly recommended to follow the instructions below in order to +upgrade to v2.4 from previous ACRN releases. + +Additional Dependencies +======================= + +Python 3.6 or above is required to build ACRN v2.4. You can check the version of +Python you are using by: + + .. code-block:: bash + + $ python3 --version + Python 3.5.2 + +Only when the reported version < 3.6 (as is the case in the example above) do +you need an upgrade. The first (and preferred) choice is to install the latest +Python 3 from the official package repository: + + .. code-block:: bash + + $ sudo apt install python3 + ... + $ python --version + Python 3.8.8 + +If this does not help, you may use the deadsnakes PPA (see below) or build from +source yourself. + + .. code-block:: bash + + $ sudo add-apt-repository ppa:deadsnakes/ppa + $ sudo apt-get update + $ sudo apt install python3.9 + $ python --version + Python 3.9.2 + +In addition, the following new tools and packages are needed to build ACRN v2.4: + + .. code-block:: bash + + $ sudo apt install libxml2-utils xsltproc + $ sudo pip3 install lxml xmlschema + +.. note:: + This is not the complete list of tools required to build ACRN. Refer to + :ref:`getting-started-building` for a complete guide to get started from + scratch. + +Configuration File Format +========================= + +Starting from v2.4, Kconfig is no longer used, and the contents of scenario +XMLs have been simplified. You need to upgrade your own Kconfig-format files +or scenario XMLs if you maintain any. + +For Kconfig-format file, you must translate your configuration to a scenario +XML where all previous Kconfig configuration entries are also available. Refer +to :ref:`scenario-config-options` for the full list of settings available in +scenario XMLs. + +For scenario XML, you need to remove the metadata in those files. You can use +the following XML transformation (in XSLT) for this purpose: + + .. code-block:: xml + + + + + + + + + + + + + + + +After saving the snippet above to a file (e.g., ``remove_metadata.xsl``), you +can use ``xsltproc`` to transform your own scenario XML: + + .. code-block:: bash + + $ xsltproc -o remove_metadata.xsl + +New Configuration Options +========================= + +The following element is added to scneario XML in v2.4. + + - :option:`hv.FEATURES.ENFORCE_TURNOFF_AC` + +To upgrade a v2.3-compliant scenario XML, you can use the following XML +transformation. The indentation in this transformation are carefully tweaked for +the best indentation in converted XML files. + + .. code-block:: xml + + + + + + + + + + + y + + + + + + + + + + + +Build Commands +============== + +While the ``make`` command-line variables are kept backward compatible, users +are recommended to update the usage of variables ``BOARD_FILE``, +``SCENARIO_FILE``, and ``RELEASE``. + + - ``BOARD_FILE`` should be replaced with ``BOARD``. There is no need to specify + ``BOARD`` and ``BOARD_FILE`` at the same time. + - Similarly, ``SCENARIO_FILE`` should be replaced with ``SCENARIO``. + - The value of ``RELEASE`` should be either ``y`` (previously was ``1``) or + ``n`` (previously was ``0``). + +``BOARD_FILE`` and ``SCENARIO_FILE`` can still be used but will take effect +only when ``BOARD`` and ``SCENARIO`` are not defined. They will be removed in +a future release. + +Patches on Generated Sources +============================ + +The C files generated from board and scenario XMLs have been removed from the +repository in v2.4. Instead they will be generated when building the +hypervisor. + +Typically you should be able to customize your scenario by modifying the +scenario XML rather than the generated files directly. But in case it is not +possible, you can still register one or more patches that will be applied to +the generated files by following the instructions in +:ref:`acrn_makefile_targets`. + +Note that modifying generated files is by no means a recommended practice. +When you find any configuration that is not flexible enough to meet your +needs, please do not hesitate to let us know by sending mail to `the mailing +list `_ or submitting issues on +`GitHub `_. Document Updates **************** @@ -76,7 +257,7 @@ New and updated reference documents are available, including: Because we dropped deprivileged boot mode support (in v2.3), we also switched our Service VM of choice away from Clear Linux and have -removed Clear Linux-specific tutorials. Deleted documents are still +removed Clear Linux–specific tutorials. Deleted documents are still available in the `version-specific v2.1 documentation `_. @@ -88,4 +269,3 @@ Fixed Issues Details Known Issues ************ - diff --git a/doc/tutorials/acrn_configuration_tool.rst b/doc/tutorials/acrn_configuration_tool.rst index 9aa0ee8d3..bd42c9928 100644 --- a/doc/tutorials/acrn_configuration_tool.rst +++ b/doc/tutorials/acrn_configuration_tool.rst @@ -152,6 +152,8 @@ toolset. Configuration Workflow +.. _acrn_makefile_targets: + Makefile Targets for Configuration ==================================