OrgACRN
/
acrn-hypervisor
mirror of https://github.com/projectacrn/acrn-hypervisor.git
1
0
Fork 0
Code Issues Releases Wiki Activity

doc: add a tutorial on how to upgrade configuration files 

Signed-off-by: Junjie Mao <junjie.mao@intel.com>
This commit is contained in:
Junjie Mao 2022-04-19 16:55:38 +08:00 committed by David Kinder
parent fd45840e67
commit 98f7dfd131
2 changed files with 71 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/develop.rst
View File

@ -40,6 +40,7 @@ Configuration Tutorials
tutorials/acrn_configuration_tool tutorials/acrn_configuration_tool
tutorials/board_inspector_tool tutorials/board_inspector_tool
tutorials/acrn_configurator_tool tutorials/acrn_configurator_tool
tutorials/upgrading_configuration
reference/config-options reference/config-options
reference/config-options-launch reference/config-options-launch
reference/hv-make-options reference/hv-make-options

70
doc/tutorials/upgrading_configuration.rst Normal file
View File

@ -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 <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:
.. 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 <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.