From 98f7dfd13194a6cd748a36ad141d3b715b3f8014 Mon Sep 17 00:00:00 2001 From: Junjie Mao Date: Tue, 19 Apr 2022 16:55:38 +0800 Subject: [PATCH] doc: add a tutorial on how to upgrade configuration files Signed-off-by: Junjie Mao --- doc/develop.rst | 1 + doc/tutorials/upgrading_configuration.rst | 70 +++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 doc/tutorials/upgrading_configuration.rst diff --git a/doc/develop.rst b/doc/develop.rst index 27b00a4aa..45f51ef64 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -40,6 +40,7 @@ Configuration Tutorials tutorials/acrn_configuration_tool tutorials/board_inspector_tool tutorials/acrn_configurator_tool + tutorials/upgrading_configuration reference/config-options reference/config-options-launch reference/hv-make-options diff --git a/doc/tutorials/upgrading_configuration.rst b/doc/tutorials/upgrading_configuration.rst new file mode 100644 index 000000000..7370eb249 --- /dev/null +++ b/doc/tutorials/upgrading_configuration.rst @@ -0,0 +1,70 @@ +.. _upgrading_configuration: + +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 +for a former release may not work for a latter if they are not upgraded. This +tutorial introduces the steps to upgrade those files. + +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 +in order to enable new features. Thus, always regenerate the board XML using the +board inspector of the new release when you upgrade. + +For the steps to use the latest board inspector, refer to +:ref:`board_inspector_tool`. + +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 +command line in the following way: + + .. code-block:: bash + + 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: + + .. 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. + +.. note:: + + 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. + +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: + + .. code-block:: bash + + 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.