.. _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.