mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-07-16 08:26:41 +00:00
doc: Update Intro to ACRN Configuration
- Update to reflect configuration changes for v3.0 Signed-off-by: Reyes, Amy <amy.reyes@intel.com>
This commit is contained in:
Reyes, Amy
David Kinder
parent
bd8c0de62b
commit
4e2ae9740f
@ -3,20 +3,14 @@
|
||||
Introduction to ACRN Configuration
|
||||
##################################
|
||||
|
||||
ACRN configuration is designed for System Integrators / Tier 1s to customize
|
||||
ACRN configuration is designed for System Integrators and Tier 1s to customize
|
||||
ACRN to meet their own needs. It allows users to adapt ACRN to target boards as
|
||||
well as configure hypervisor capabilities and provision VMs.
|
||||
|
||||
ACRN configuration consists of the following key components.
|
||||
|
||||
* Configuration data saved as XML files.
|
||||
* A configuration toolset that helps users to generate and edit configuration
|
||||
data. The toolset includes:
|
||||
|
||||
- **Board Inspector**: Collects board-specific information on target
|
||||
machines.
|
||||
- **ACRN Configurator**: Enables you to edit configuration data via a
|
||||
web-based UI.
|
||||
* A configuration toolset to generate and edit configuration data.
|
||||
|
||||
The following sections introduce the concepts and tools of ACRN configuration
|
||||
from the aspects below.
|
||||
@ -25,16 +19,14 @@ from the aspects below.
|
||||
different types of configuration data.
|
||||
* :ref:`acrn_config_workflow` overviews the steps to customize ACRN
|
||||
configuration using the configuration toolset.
|
||||
* :ref:`acrn_config_data` explains the location and format of configuration
|
||||
data saved as XML files.
|
||||
|
||||
.. _acrn_config_types:
|
||||
|
||||
Types of Configurations
|
||||
***********************
|
||||
|
||||
ACRN includes three types of configurations: board, scenario, and launch. The
|
||||
configuration data are saved in three XML files. The following sections briefly
|
||||
ACRN includes two types of configurations: board and scenario. The
|
||||
configuration data are saved in XML files. The following sections briefly
|
||||
describe the objectives and main contents of each file.
|
||||
|
||||
Board Configuration File
|
||||
@ -60,9 +52,8 @@ Scenario Configuration File
|
||||
===========================
|
||||
|
||||
The scenario configuration file defines a working scenario by configuring
|
||||
hypervisor capabilities and defining some VM attributes and resources.
|
||||
We call these settings "static" because they are used to build the hypervisor.
|
||||
You can specify the following information in a scenario configuration:
|
||||
hypervisor capabilities and defining VM attributes and resources. Examples of
|
||||
parameters:
|
||||
|
||||
* Hypervisor capabilities
|
||||
|
||||
@ -83,46 +74,29 @@ You can specify the following information in a scenario configuration:
|
||||
- User VM settings, such as boot protocol and VM OS kernel parameters.
|
||||
- Settings of virtual devices, such as virtual UARTs.
|
||||
|
||||
You need a scenario configuration file to build an ACRN hypervisor. The
|
||||
build process uses the file to build a hypervisor that can initialize its
|
||||
capabilities and set up the VMs at runtime.
|
||||
You need a scenario configuration file to build an ACRN hypervisor. The build process uses the file to build a hypervisor that can initialize its capabilities and set up the VMs at runtime.
|
||||
|
||||
The scenario configuration defines User VMs as follows:
|
||||
For pre-launched User VMs, all attributes and resources are static
|
||||
configurations. The VM attributes and resources are exactly the amount of
|
||||
resources allocated to them.
|
||||
|
||||
* For pre-launched User VMs, the scenario configuration defines all attributes
|
||||
and resources (these VMs have static configurations by nature). The VM
|
||||
attributes and resources are exactly the amount
|
||||
of resources allocated to them.
|
||||
|
||||
* For post-launched User VMs, the scenario configuration defines only static
|
||||
attributes and resources. Other resources are under the control of the
|
||||
Service VM and can be dynamically allocated to these VMs via launch
|
||||
scripts.
|
||||
|
||||
Launch Configuration File for Launch Scripts
|
||||
============================================
|
||||
|
||||
The launch configuration file applies only to scenarios that have
|
||||
post-launched User VMs. The file defines certain attributes and
|
||||
resources of the post-launched VMs specified in the scenario configuration
|
||||
file. We call these settings "dynamic" because they are used at runtime.
|
||||
|
||||
You need a launch configuration file to generate a launch script (shell script)
|
||||
for each post-launched User VM. The launch script invokes the
|
||||
Service VM's :ref:`Device Model <hld-devicemodel>` ``acrn-dm`` to create
|
||||
the VM. Unlike board and scenario configurations used at build time or by
|
||||
ACRN hypervisor, launch configurations are used dynamically in the Service VM.
|
||||
For post-launched User VMs, some resources are static configurations. Other
|
||||
resources are under the control of the Service VM and can be dynamically
|
||||
allocated to a VM via a launch script.
|
||||
|
||||
.. _acrn_config_workflow:
|
||||
|
||||
Using ACRN Configuration Toolset
|
||||
********************************
|
||||
|
||||
The ACRN configuration toolset enables you to create
|
||||
and edit configuration data. The toolset consists of the following:
|
||||
The ACRN configuration toolset lets you create and edit configuration data. The
|
||||
toolset includes:
|
||||
|
||||
* :ref:`Board Inspector <board_inspector_tool>`
|
||||
* :ref:`ACRN Configurator <acrn_configurator_tool>`
|
||||
* :ref:`Board Inspector <board_inspector_tool>`: Collects information from your
|
||||
target machine and generates a board configuration file.
|
||||
* :ref:`ACRN Configurator <acrn_configurator_tool>`: Provides a graphical user
|
||||
interface (GUI) for configuring your hypervisor and VM parameters, and
|
||||
generates a scenario configuration file and launch scripts.
|
||||
|
||||
As introduced in :ref:`overview_dev`, configuration takes place at
|
||||
:ref:`overview_dev_board_config` and :ref:`overview_dev_config_editor` in
|
||||
@ -132,73 +106,3 @@ the overall development process:
|
||||
|
||||
ACRN source also includes makefile targets to aid customization. See
|
||||
:ref:`hypervisor-make-options`.
|
||||
|
||||
.. _acrn_config_data:
|
||||
|
||||
ACRN Configuration Data
|
||||
***********************
|
||||
|
||||
The following sections explain the format of the board, scenario, and launch
|
||||
configuration files. Although we recommend using the ACRN configuration toolset
|
||||
to create these files, this reference may be useful for advanced usage and
|
||||
troubleshooting.
|
||||
|
||||
ACRN source code offers predefined XMLs, and the generic templates used for
|
||||
new boards and scenarios, in the ``misc/config_tools/data/`` directory of
|
||||
the ``acrn-hypervisor`` repo.
|
||||
|
||||
Board XML Format
|
||||
================
|
||||
|
||||
The board XML has an ``acrn-config`` root element and a
|
||||
``board`` attribute:
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<acrn-config board="BOARD">
|
||||
|
||||
The ``board`` attribute defines the board name and must match the
|
||||
``board`` attribute in the scenario configuration file and the launch
|
||||
configuration file. The file name of the board configuration file
|
||||
(example: ``my_board.xml``) doesn't affect the board name.
|
||||
|
||||
Board XML files are input to the ACRN Configurator tool and the build system,
|
||||
and are not intended for end users to modify.
|
||||
|
||||
Scenario XML Format
|
||||
===================
|
||||
|
||||
The scenario XML has an ``acrn-config`` root element as well as ``board`` and
|
||||
``scenario`` attributes:
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<acrn-config board="BOARD" scenario="SCENARIO">
|
||||
|
||||
The ``board`` attribute specifies the board name and must match the ``board``
|
||||
attribute in the board configuration file.
|
||||
|
||||
The ``scenario`` attribute specifies the scenario name, followed by hypervisor
|
||||
and VM settings.
|
||||
|
||||
See :ref:`scenario-config-options` for a full explanation of available scenario
|
||||
XML elements.
|
||||
|
||||
Launch XML Format
|
||||
=================
|
||||
|
||||
The launch XML has an ``acrn-config`` root element as well as
|
||||
``board``, ``scenario``, and ``user_vm_launcher`` attributes:
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<acrn-config board="BOARD" scenario="SCENARIO" user_vm_launcher="USER_VM_NUMBER">
|
||||
|
||||
The ``board`` attribute specifies the board name and must match the ``board``
|
||||
attribute in the board configuration file and the scenario configuration file.
|
||||
|
||||
The ``scenario`` attribute specifies the scenario name and must match the
|
||||
``scenario`` attribute in the scenario configuration file.
|
||||
|
||||
The ``user_vm_launcher`` attribute specifies the number of post-launched User
|
||||
VMs in a scenario.
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
Upgrading ACRN Configurations to Recent Releases
|
||||
################################################
|
||||
|
||||
The configuration files, introduced in :ref:`acrn_config_data`, are refined
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user