From c925d63dd919889200d3181e69cd6d1feb46b231 Mon Sep 17 00:00:00 2001 From: "Reyes, Amy" Date: Thu, 5 May 2022 15:01:22 -0700 Subject: [PATCH] doc: Copyedit upgrading_configuration.rst - Grammatical and formatting cleanup Signed-off-by: Reyes, Amy --- doc/tutorials/upgrading_configuration.rst | 56 ++++++++++++----------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/doc/tutorials/upgrading_configuration.rst b/doc/tutorials/upgrading_configuration.rst index 7370eb249..7b5cf72b4 100644 --- a/doc/tutorials/upgrading_configuration.rst +++ b/doc/tutorials/upgrading_configuration.rst @@ -3,9 +3,9 @@ Upgrading ACRN Configurations to Recent Releases ################################################ -The configurations files, introduced in :ref:`acrn_config_data`, are refined -every release for richer features, clearer organizations, and more user friendly -representations. Due to the strict validation ACRN adopts, configuration files +The configuration files, introduced in :ref:`acrn_config_data`, are refined +every release for richer features, clearer organization, and more user-friendly +presentation. Due to the strict validation ACRN adopts, configuration files for a former release may not work for a latter if they are not upgraded. This tutorial introduces the steps to upgrade those files. @@ -13,11 +13,11 @@ Board XML ********* A board XML file lists the characteristics of a board and is generated by the -board inspector. Each release of ACRN adds some more information into that file +Board Inspector. Each ACRN release adds more information to that file in order to enable new features. Thus, always regenerate the board XML using the -board inspector of the new release when you upgrade. +Board Inspector of the new release when you upgrade. -For the steps to use the latest board inspector, refer to +For the steps to use the latest Board Inspector, refer to :ref:`board_inspector_tool`. Scenario XML @@ -26,23 +26,27 @@ Scenario XML A scenario XML file captures the configurations of hypervisor features and definitions of VMs. Starting from v3.0, the highly recommended way to upgrade a scenario XML is to use the scenario XML upgrader found at -``misc/config_tools/scenario_config/upgrader.py``. Invoke this script from the +``misc/config_tools/scenario_config/upgrader.py``. Run this script from the command line in the following way: - .. code-block:: bash +.. code-block:: bash - misc/config_tools/scenario_config/upgrader.py + misc/config_tools/scenario_config/upgrader.py -```` is the path to the scenario XML file for a previous -release. This script will generate a new scenario XML file, located at ````, by migrating, following the latest schema, as many data in ```` as possible. If there is any data that cannot be migrated, the -script will generate messages like this: +* ```` is the path to the scenario XML file for a previous + release. - .. code-block:: console +* ```` is the path to the new scenario XML file generated by the + script. - WARNING:root:hv/DEBUG_OPTIONS/some = '1' is discarded - INFO:root:vm[1]/os_config/name = 'OS Name': Guest OS names are no longer needed in scenario definitions. +The script generates the new scenario XML file by migrating as many data in +```` as possible, based on the latest schema. If any data +cannot be migrated, the script generates messages. For example: + +.. code-block:: console + + WARNING:root:hv/DEBUG_OPTIONS/some = '1' is discarded + INFO:root:vm[1]/os_config/name = 'OS Name': Guest OS names are no longer needed in scenario definitions. A warning message indicates that some data are discarded unintendedly, while an info message indicates an intended drop of obsoleted data. @@ -52,19 +56,19 @@ info message indicates an intended drop of obsoleted data. The upgrader's best efforts at migrating data from scenario XMLs of former releases do not guarantee that all data can be migrated. Thus, you should carefully review all messages from the upgrader tool. In case any meaningful - data is lost, use the ACRN configurator to open the upgraded scenario XML for - further edits. + data is lost, use the :ref:`ACRN Configurator ` to + open the upgraded scenario XML for further edits. Launch XML ********** -Starting from ACRN v3.0, data in a launch XML are merged into the -scenario XML. The same upgrader can be used to upgrade a pair of scenario XML -and launch XML: +Starting from ACRN v3.0, data in a launch XML are merged into the scenario XML. +You can use the same upgrader tool to upgrade a pair of scenario XML and launch +XML files into the merged format: - .. code-block:: bash +.. code-block:: bash - misc/config_tools/scenario_config/upgrader.py --launch + misc/config_tools/scenario_config/upgrader.py --launch -The upgrader will then migrate all data in both XMLs and show messages about -discarded data in the same way as upgrading a scenario XML alone. +The upgrader migrates all data in both XMLs into the ```` and shows +messages about discarded data in the same way as upgrading a scenario XML alone.