github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2026-01-20 09:04:39 +00:00
Code Issues Projects Releases Wiki Activity

doc: update draft 3.0 published docs to include changes on master

Browse Source 
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder
2022-06-16 21:03:45 -07:00
committed by David Kinder
parent 4a7d6e4119
commit 4bfbab8d89
12 changed files with 161 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
doc/tutorials/acrn_configuration_tool.rst
View File

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

1
doc/tutorials/acrn_configurator_tool.rst
View File

@@ -25,7 +25,6 @@ This guide assumes you have a board configuration file and have successfully
launched the ACRN Configurator. For steps, see the following Getting Started
Guide sections:
* :ref:`gsg-target-hardware`
* :ref:`gsg-dev-computer`
* :ref:`gsg-board-setup`
* :ref:`gsg-dev-setup`

55
doc/tutorials/board_inspector_tool.rst
View File

@@ -13,21 +13,28 @@ configuration file on the target system. The board configuration file stores
hardware-specific information extracted from the target platform and is used to
customize your :ref:`ACRN configuration <acrn_configuration_tool>`.
Prerequisites
*************
This guide assumes you have set up your target system and successfully launched
the Board Inspector. For steps, see the following Getting Started Guide
sections:
* :ref:`gsg-dev-computer`
* :ref:`gsg-board-setup`
Generate a Board Configuration File
***********************************
.. important::
Whenever you change the configuration of the board, such as BIOS settings,
additional memory, or PCI devices, you must generate a new board
configuration file.
Whenever you change the configuration of the board, such as peripherals, BIOS
settings, additional memory, USB devices, or PCI devices, you must generate a
new board configuration file.
The following steps describe all options in the Board Inspector for generating
a board configuration file.
#. Make sure the target system is set up and ready to run the Board Inspector,
according to :ref:`gsg-board-setup` in the Getting Started Guide.
#. Run the Board Inspector tool (``board_inspector.py``) to generate the board
configuration file. This example assumes the tool is in the
``~/acrn-work/`` directory and ``my_board`` is the desired file
@@ -35,14 +42,8 @@ a board configuration file.
.. code-block:: bash
cd ~/acrn-work/board_inspector/
sudo python3 board_inspector.py my_board
Upon success, the tool displays a message similar to this example:
.. code-block:: console
my_board.xml saved successfully!
cd ~/acrn-work
sudo board_inspector.py my_board
#. Confirm that the board configuration file ``my_board.xml`` was generated in
the current directory.
@@ -58,7 +59,9 @@ Board Inspector with the ``-h`` option yields the following usage message:
.. code-block::
usage: board_inspector.py [-h] [--out OUT] [--basic] [--loglevel LOGLEVEL]
[--check-device-status] board_name
[--check-device-status]
[--add-llc-cat <capacity_mask_length:int>,<clos_number:int>,<has_CDP:bool>]
board_name
positional arguments:
board_name the name of the board that runs the ACRN hypervisor
@@ -66,11 +69,15 @@ Board Inspector with the ``-h`` option yields the following usage message:
optional arguments:
-h, --help show this help message and exit
--out OUT the name of board info file
--basic do not extract advanced information such as ACPI namespace
--loglevel LOGLEVEL choose log level, e.g. info, warning or error
--basic do not extract advanced information such as ACPI
namespace
--loglevel LOGLEVEL choose log level, e.g. debug, info, warning, error or
critical
--check-device-status
filter out devices whose _STA object evaluates to 0
--add-llc-cat <capacity_mask_length:int>,<clos_number:int>,<has_CDP:bool>
manually set the Cache Allocation Technology
capability of the last level cache
Details about certain arguments:
@@ -98,8 +105,7 @@ Details about certain arguments:
of board configuration files.
* - ``--loglevel``
- Optional. Choose log level, e.g., info, warning or error.
(Default is warning.)
- Optional. Choose the log level. (Default is warning.)
* - ``--check-device-status``
- Optional. On some boards, the device status (reported by the _STA
@@ -107,3 +113,12 @@ Details about certain arguments:
pass-through devices. By default, the Board Inspector includes the
devices in the board configuration file. This option filters out the
devices, so that they cannot be used.
* - ``--add-llc-cat``
- Optional. Add the Cache Allocation Technology (CAT) capabilities of the
last level cache (LLC) to the generated board configuration file even
when the hardware does not report them for any reason. For example,
``--add-llc-cat=12,16,y``. CDP (Code and Data Prioritization) performance
feature enables separate control over code and data placement in the
processor's cache. Valid values for ``bool`` are
``true|false|y|n|yes|no``.

2
doc/tutorials/upgrading_configuration.rst
View File

@@ -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