doc: Copyedit upgrading_configuration.rst
Grammatical and formatting cleanup
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,18 +26,22 @@ 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
misc/config_tools/scenario_config/upgrader.py <your scenario XML> <out file>
-``<your scenario XML>`` is the path to the scenario XML file for a previous
-release. This script will generate a new scenario XML file, located at ``<out
-file>``, by migrating, following the latest schema, as many data in ``<your
-scenario XML>`` as possible. If there is any data that cannot be migrated, the
-script will generate messages like this:
+* ``<your scenario XML>`` is the path to the scenario XML file for a previous
+ release.
+
+* ``<out file>`` is the path to the new scenario XML file generated by the
+ script.
+
+The script generates the new scenario XML file by migrating as many data in
+``<your scenario XML>`` as possible, based on the latest schema. If any data
+cannot be migrated, the script generates messages. For example:
.. code-block:: console
@@ -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 <acrn_configurator_tool>` 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
misc/config_tools/scenario_config/upgrader.py <your scenario XML> --launch <your launch XML> <out file>
-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 ``<out file>`` and shows
+messages about discarded data in the same way as upgrading a scenario XML alone.
