75 lines
2.9 KiB
ReStructuredText
75 lines
2.9 KiB
ReStructuredText
.. _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.
|