github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-23 22:18:17 +00:00
Code Issues Projects Releases Wiki Activity

doc: add descriptions to hypervisor configuration targets

Browse Source 
This patch adds explanations and examples of the makefile targets for hypervisor
configuration, including `hvdefconfig`, `hvshowconfig`, `hvdiffconfig` and
`hvapplydiffconfig`.

Tracked-On: #5644
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
Junjie Mao 2021-03-05 13:39:29 +08:00 committed by fitchbe
parent 42fd1b1d5c
commit bc099a7e71
3 changed files with 128 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
doc/getting-started/building-from-source.rst
View File

@ -12,9 +12,9 @@ The hypervisor binary is generated based on configuration settings in XML
files. Instructions about customizing these settings can be found in
:ref:`getting-started-hypervisor-configuration`.
One binary for all platforms and all usage scenarios is currently not
supported, primarily because dynamic configuration parsing is restricted in
the ACRN hypervisor for the following reasons:
One binary for all platforms and all usage scenarios is not
supported. Dynamic configuration parsing is not used in
the ACRN hypervisor for these reasons:
- **Maintain functional safety requirements.** Implementing dynamic parsing
introduces dynamic objects, which violate functional safety requirements.
@ -90,15 +90,15 @@ ACRN.
Get the ACRN Hypervisor Source Code
***********************************
The `acrn-hypervisor <https://github.com/projectacrn/acrn-hypervisor/>`_
The `ACRN hypervisor <https://github.com/projectacrn/acrn-hypervisor/>`_
repository contains four main components:
1. The ACRN hypervisor code, located in the ``hypervisor`` directory.
#. The ACRN device model code, located in the ``devicemodel`` directory.
#. The ACRN debug tools source code, located in the ``misc/debug_tools`` directory.
#. The ACRN online services source code, located in the ``misc/services`` directory.
1. The ACRN hypervisor code is in the ``hypervisor`` directory.
#. The ACRN device model code is in the ``devicemodel`` directory.
#. The ACRN debug tools source code is in the ``misc/debug_tools`` directory.
#. The ACRN online services source code is in the ``misc/services`` directory.
Enter the following to get the acrn-hypervisor source code:
Enter the following to get the ACRN hypervisor source code:
.. code-block:: none
@ -123,10 +123,10 @@ LOGICAL_PARTITION:
This scenario defines two pre-launched VMs.
INDUSTRY:
This is a typical scenario for industrial usage with up to eight VMs:
This scenario is an example for industrial usage with up to eight VMs:
one pre-launched Service VM, five post-launched Standard VMs (for Human
interaction etc.), one post-launched RT VMs (for real-time control),
and one Kata container VM.
and one Kata Container VM.
HYBRID:
This scenario defines a hybrid use case with three VMs: one
@ -138,15 +138,15 @@ HYBRID_RT:
pre-launched RTVM, one pre-launched Service VM, and one post-launched
Standard VM.
XML configuration files for those scenarios on supported boards are available
XML configuration files for these scenarios on supported boards are available
under the ``misc/config_tools/data`` directory.
Assuming that you are at the top level of the ``acrn-hypervisor`` directory, perform
the following to build the hypervisor, device model and tools:
the following to build the hypervisor, device model, and tools:
.. note::
The debug version is built by default. To build a release version, a user
must builds with ``RELEASE=y`` explicitly, regardless of whether a previous
The debug version is built by default. To build a release version,
build with ``RELEASE=y`` explicitly, regardless of whether a previous
build exists.
* Build the debug version of ``INDUSTRY`` scenario on the ``nuc7i7dnb``:
@ -209,7 +209,7 @@ The build results are found in the ``build`` directory. You can specify
a different build directory by setting the ``O`` ``make`` parameter,
for example: ``make O=build-nuc``.
To query the board, scenario and build type of an existing build, the
To query the board, scenario, and build type of an existing build, the
``hvshowconfig`` target will help.
.. code-block:: none
@ -239,7 +239,8 @@ scenario XML.
The following commands show how to customize manually the scenario XML based on
the predefined ``INDUSTRY`` scenario for ``nuc7i7dnb`` and rebuild the
hypervisor.
hypervisor. The ``hvdefconfig`` target generates the configuration files without
building the hypervisor, allowing users to tweak the configurations.
.. code-block:: none
@ -249,12 +250,12 @@ hypervisor.
$ make
.. note::
A hypervisor build memorizes the board and scenario previously
A hypervisor build remembers the board and scenario previously
configured. Thus, there is no need to duplicate BOARD and SCENARIO in the
second ``make`` above.
While the scenario XML files can be changed manually, we recommend to use the
ACRN web-based configuration app which provides valid options and descriptions
While the scenario XML files can be changed manually, we recommend you use the
ACRN web-based configuration app that provides valid options and descriptions
of the configuration entries. Refer to :ref:`acrn_config_tool_ui` for more
instructions.

114
doc/tutorials/acrn_configuration_tool.rst
View File

@ -9,13 +9,13 @@ well as configure hypervisor capabilities and provision VMs.
ACRN configuration consists of the following key components.
- Configuration data which are saved as XML files.
- Configuration data saved as XML files.
- A configuration toolset that helps users to generate and edit configuration
data. The toolset includes:
- A **board inspector** which collects board-specific information on target
- A **board inspector** that collects board-specific information on target
machines.
- A **configuration editor** which edits configuration data via web-based UI.
- A **configuration editor** that lets you edit configuration data via a web-based UI.
The following sections introduce the concepts and tools of ACRN configuration
from the aspects below.
@ -25,7 +25,7 @@ from the aspects below.
- :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 which are saved as XML files.
data saved as XML files.
- :ref:`acrn_config_tool_ui` gives detailed instructions on using the
configuration editor.
@ -34,7 +34,7 @@ from the aspects below.
Types of Configurations
***********************
ACRN includes three types of configurations: board, scenario and launch. The
ACRN includes three types of configurations: board, scenario, and launch. The
following sections briefly describe the objectives and main contents of each
type.
@ -43,7 +43,7 @@ Board Configuration
The board configuration stores hardware-specific information extracted on the
target platform. It describes the capacity of hardware resources (such as
processors and memory), platform power states, available devices and BIOS
processors and memory), platform power states, available devices, and BIOS
versions. This information is used by ACRN configuration tool to check feature
availability and allocate resources among VMs, as well as by ACRN hypervisor to
initialize and manage the platform at runtime.
@ -61,7 +61,7 @@ following in scenario configuration.
- Hypervisor capabilities
- Availability and settings of hypervisor features, such as debugging
facilities, scheduling algorithm, ivshmem and security features.
facilities, scheduling algorithm, ivshmem, and security features.
- Hardware management capacity of the hypervisor, such as maximum PCI devices
and maximum interrupt lines supported.
- Memory consumption of the hypervisor, such as the entry point and stack
@ -72,7 +72,7 @@ following in scenario configuration.
- VM attributes, such as VM names.
- Maximum number of VMs supported.
- Resources allocated to each VM, such as number of vCPUs, amount of guest
memory and pass-through devices.
memory, and pass-through devices.
- Guest OS settings, such as boot protocol and guest kernel parameters.
- Settings of virtual devices, such as virtual UARTs.
@ -91,9 +91,9 @@ Launch Configuration
The launch configuration defines the attributes and resources of a
post-launched VM. The main contents are similar to the VM attributes and
resources in scenario configuration. It is used to generate shell scripts that
resources in scenario configuration. The launch configuration is used to generate shell scripts that
invoke ``acrn-dm`` to create post-launched VMs. Unlike board and scenario
configurations which are used at build time or by ACRN hypervisor, launch
configurations used at build time or by ACRN hypervisor, launch
configuration are used dynamically in the Service VM.
.. _acrn_config_workflow:
@ -130,12 +130,12 @@ toolset.
#. Run the ACRN configuration editor (available at
``misc/config_tools/config_app/app.py``) on the host machine and import
the ``$(BOARD).xml``. Select your working scenario under **Scenario Setting**
and input the desired scenario settings. The tool will do a sanity check
and input the desired scenario settings. The tool will do validation checks
on the input based on the ``$(BOARD).xml``. The customized settings can be
exported to your own ``$(SCENARIO).xml``. If you have a customized scenario
XML file, you can also import it to the editor for modification.
#. In ACRN configuration editor, input the launch script parameters for the
post-launched User VM under **Launch Setting**. The editor will sanity check
post-launched User VM under **Launch Setting**. The editor will validate
the input based on both the ``$(BOARD).xml`` and ``$(SCENARIO).xml`` and then
export settings to your ``$(LAUNCH).xml``.
@ -152,6 +152,86 @@ toolset.
Configuration Workflow
Makefile Targets for Configuration
==================================
In addition to the ``BOARD`` and ``SCENARIO`` variables, ACRN source also
includes the following makefile targets to aid customization.
.. list-table::
:widths: 20 50
:header-rows: 1
* - Target
- Description
* - ``hvdefconfig``
- Generate configuration files (a bunch of C source files) in the
build directory without building the hypervisor. This target can be used
when you want to customize the configurations based on a predefined
scenario.
* - ``hvshowconfig``
- Print the target ``BOARD``, ``SCENARIO`` and build type (debug or
release) of a build.
* - ``hvdiffconfig``
- After modifying the generated configuration files, you can use this
target to generate a patch that shows the differences made.
* - ``hvapplydiffconfig PATCH=/path/to/patch``
- Register a patch to be applied on the generated configuration files
every time they are regenerated. The ``PATCH`` variable specifies the path
(absolute or relative to current working directory) of the
patch. Multiple patches can be registered by invoking this target
multiple times.
The targets ``hvdiffconfig`` and ``hvapplydiffconfig``
are provided for users who already have offline patches to the generated
configuration files. Prior to v2.4, the generated configuration files are also
in the repository. Some users may already have chosen to modify these files
directly to customize the configurations.
.. note::
We highly recommend new users save and maintain customized configurations
in XML, not in patches to generated configuration files.
Here is an example how to use the ``hvdiffconfig`` to generate a patch and save
it to ``config.patch``.
.. code-block:: console
acrn-hypervisor$ make BOARD=ehl-crb-b SCENARIO=hybrid_rt hvdefconfig
...
acrn-hypervisor$ vim build/hypervisor/configs/scenarios/hybrid_rt/pci_dev.c
(edit the file manually)
acrn-hypervisor$ make hvdiffconfig
...
Diff on generated configuration files is available at /path/to/acrn-hypervisor/build/hypervisor/config.patch.
To make a patch effective, use 'applydiffconfig PATCH=/path/to/patch' to register it to a build.
...
acrn-hypervisor$ cp build/hypervisor/config.patch config.patch
The example below shows how to use ``hvapplydiffconfig`` to apply
``config.patch`` to a new build.
.. code-block:: console
acrn-hypervisor$ make clean
acrn-hypervisor$ make BOARD=ehl-crb-b SCENARIO=hybrid_rt hvdefconfig
...
acrn-hypervisor$ make hvapplydiffconfig PATCH=config.patch
...
/path/to/acrn-hypervisor/config.patch is registered for build directory /path/to/acrn-hypervisor/build/hypervisor.
Registered patches will be applied the next time 'make' is invoked.
To unregister a patch, remove it from /path/to/acrn-hypervisor/build/hypervisor/configs/.diffconfig.
...
acrn-hypervisor$ make hypervisor
...
Applying patch /path/to/acrn-hypervisor/config.patch:
patching file scenarios/hybrid_rt/pci_dev.c
...
.. _acrn_config_data:
ACRN Configuration Data
@ -177,7 +257,7 @@ The board XML has an ``acrn-config`` root element and a ``board`` attribute:
<acrn-config board="BOARD">
As an input to the configuration editor and the build system, board XMLs are not
Board XML files are input to the configuration editor and the build system, and are not
intended for end users to modify.
Scenario XML Format
@ -287,7 +367,7 @@ Use the ACRN Configuration Editor
The ACRN configuration editor provides a web-based user interface for the following:
- reads board info
- configures and validates scenario and launch configurationss
- configures and validates scenario and launch configurations
- generates launch scripts for the specified post-launched User VMs.
- dynamically creates a new scenario configuration and adds or deletes VM
settings in it
@ -300,7 +380,7 @@ Prerequisites
.. _get acrn repo guide:
https://projectacrn.github.io/latest/getting-started/building-from-source.html#get-the-acrn-hypervisor-source-code
- Clone acrn-hypervisor:
- Clone the ACRN hypervisor repo::
.. code-block:: none
@ -409,7 +489,7 @@ Instructions
pop-up model.
.. note::
All customized scenario XMLs will be in user-defined groups, which are
All customized scenario XMLs will be in user-defined groups
located in ``misc/config_tools/data/[board]/user_defined/``.
Before saving the scenario XML, the configuration editor validates the
@ -441,7 +521,7 @@ The **Launch Setting** is quite similar to the **Scenario Setting**:
#. Configure the items for the current launch configuration.
#. To dynamically add or remove User VM (UOS) launch scripts:
#. Add or remove User VM (UOS) launch scripts:
- Add a UOS launch script by clicking **Configure an UOS below** for the
current launch configuration.

20
doc/tutorials/vuart_configuration.rst
View File

@ -10,9 +10,9 @@ The virtual universal asynchronous receiver/transmitter (vUART) supports
two functions: one is the console, the other is communication. vUART
only works on a single function.
Currently, only two vUART configurations are added to the predefined scenarios,
Only two vUART configurations are added to the predefined scenarios,
but you can customize the scenarios to enable more using the :ref:`ACRN
configuration toolset <acrn_config_workflow>`
configuration toolset <acrn_config_workflow>`.
Console Enable List
===================
@ -69,7 +69,7 @@ The port_base and IRQ should differ from the ``vuart[0]`` in the same VM.
``t_vuart.vm_id`` is the target VM's vm_id, start from 0. (0 means VM0)
``t_vuart.vuart_id`` is the target vuart index in the target VM. Start
``t_vuart.vuart_id`` is the target vUART index in the target VM. Start
from ``1``. (``1`` means ``vuart[1]``)
Example:
@ -200,7 +200,7 @@ started, as shown in the diagram below:
.. note::
For operating systems such as VxWorks and Windows that depend on the
ACPI table to probe the UART driver, adding the vUART configuration in
the hypervisor is not sufficient. Currently, we recommend that you use
the hypervisor is not sufficient. We recommend that you use
the configuration in the figure 3 data flow. This may be refined in the
future.
@ -229,7 +229,7 @@ to 8 vUART for each VM, from ``vuart_idx=0`` to ``vuart_idx=7``.
Suppose we use vUART0 for a port with ``vuart_idx=0``, vUART1 for
``vuart_idx=1``, and so on.
Please pay attention to these points:
Pay attention to these points:
* vUART0 is the console port, vUART1-vUART7 are inter-VM communication ports.
* Each communication port must set the connection to another communication vUART port of another VM.
@ -304,7 +304,7 @@ The ACRN vUART related XML fields:
legacy ``vuart[0]`` configuration, ``id=1`` is for ``vuart[1]``.
- ``type`` in ``<legacy_vuart>``, type is always ``VUART_LEGACY_PIO``
for legacy vUART.
- ``base`` in ``<legacy_vuart>``, if use the legacy vUART port, set
- ``base`` in ``<legacy_vuart>``, if using the legacy vUART port, set
COM1_BASE for ``vuart[0]``, set ``COM2_BASE`` for ``vuart[1]``.
``INVALID_COM_BASE`` means do not use the legacy vUART port.
- ``irq`` in ``<legacy_vuart>``, if you use the legacy vUART port, set
@ -324,8 +324,8 @@ Run the command to build ACRN with this XML configuration file::
The configuration tools will test your settings, and check :ref:`vUART
Rules <index-of-vuart>` for compilation issue. After compiling, you can find
the generated sources under
``build/hypervisor/configs/scenarios/<scenario>/pci_dev.c``
which is based on the XML settings, something like:
``build/hypervisor/configs/scenarios/<scenario>/pci_dev.c``,
based on the XML settings, something like:
.. code-block:: none
@ -342,7 +342,7 @@ which is based on the XML settings, something like:
},
}
This struct shows a PCI-vUART with ``vuart_idx=1``, ``BDF 00:05.0``, its
This struct shows a PCI-vUART with ``vuart_idx=1``, ``BDF 00:05.0``, it's
a PCI-vUART1 of
VM0, and it is connected to VM1's vUART1 port. When VM0 wants to communicate
with VM1, it can use ``/dev/ttyS*``, the character device file of
@ -388,6 +388,6 @@ Kernel Cmdline for PCI-vUART Console
When an ACRN VM does not have a legacy ``vuart[0]`` but has a
PCI-vUART0, you can use PCI-vUART0 for VM serial input/output. Check
which tty has the BDF of PCI-vUART0; usually it is not ``/dev/ttyS0``.
which TTY has the BDF of PCI-vUART0; usually it is not ``/dev/ttyS0``.
For example, if ``/dev/ttyS4`` is PCI-vUART0, you must set
``console=/dev/ttyS4`` in the kernel cmdline.