1.. _upgrading_configuration:
2
3Upgrading ACRN Configurations to Recent Releases
4################################################
5
6The configuration files, introduced in :ref:`acrn_config_types`, are refined
7every release for richer features, clearer organization, and more user-friendly
8presentation. Due to the strict validation ACRN adopts, configuration files
9for a former release may not work for a latter if they are not upgraded. This
10tutorial introduces the steps to upgrade those files.
11
12Board XML
13*********
14
15A board XML file lists the characteristics of a board and is generated by the
16Board Inspector. Each ACRN release adds more information to that file
17in order to enable new features. Thus, always regenerate the board XML using the
18Board Inspector of the new release when you upgrade.
19
20For the steps to use the latest Board Inspector, refer to
21:ref:`board_inspector_tool`.
22
23Scenario XML
24************
25
26A scenario XML file captures the configurations of hypervisor features and
27definitions of VMs. Starting from v3.0, the highly recommended way to upgrade a
28scenario XML is to use the scenario XML upgrader found at
29``misc/config_tools/scenario_config/upgrader.py``. Run this script from the
30command line in the following way:
31
32.. code-block:: bash
33
34   misc/config_tools/scenario_config/upgrader.py <your scenario XML> <out file>
35
36* ``<your scenario XML>`` is the path to the scenario XML file for a previous
37  release.
38
39* ``<out file>`` is the path to the new scenario XML file generated by the
40  script.
41
42The script generates the new scenario XML file by migrating as many data in
43``<your scenario XML>`` as possible, based on the latest schema. If any data
44cannot be migrated, the script generates messages. For example:
45
46.. code-block:: console
47
48   WARNING:root:hv/DEBUG_OPTIONS/some = '1' is discarded
49   INFO:root:vm[1]/os_config/name = 'OS Name': Guest OS names are no longer needed in scenario definitions.
50
51A warning message indicates that some data are discarded unintendedly, while an
52info message indicates an intended drop of obsoleted data.
53
54.. note::
55
56   The upgrader's best efforts at migrating data from scenario XMLs of former
57   releases do not guarantee that all data can be migrated. Thus, you should
58   carefully review all messages from the upgrader tool. In case any meaningful
59   data is lost, use the :ref:`ACRN Configurator <acrn_configurator_tool>` to
60   open the upgraded scenario XML for further edits.
61
62Launch XML
63**********
64
65Starting from ACRN v3.0, data in a launch XML are merged into the scenario XML.
66You can use the same upgrader tool to upgrade a pair of scenario XML and launch
67XML files into the merged format:
68
69.. code-block:: bash
70
71   misc/config_tools/scenario_config/upgrader.py --launch <your launch XML> <your scenario XML> <out file>
72
73The upgrader migrates all data in both XMLs into the ``<out file>`` and shows
74messages about discarded data in the same way as upgrading a scenario XML alone.
75