.. _upgrading_configuration:

Upgrading ACRN Configurations to Recent Releases
################################################

The configuration files, introduced in :ref:`acrn_config_types`, 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.

Board XML
*********

A board XML file lists the characteristics of a board and is generated by the
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.

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

* ``<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

   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 :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.
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 --launch <your launch XML> <your scenario XML> <out file>

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.