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

doc: create ACRN config tool/board inspector docs

Browse Source 
- Create ACRN config tool doc based on info in existing "Intro to ACRN Configuration" doc, add clarifications
- Create board inspector tool doc based on info in existing "Intro to ACRN Configuration" doc, add clarifications
- Create launch config options doc based on info in existing "Intro to ACRN Configuration" doc, similar to existing scenario config options doc
- Update refs that no longer exist
- Create hypervisor makefile options doc, combining makefile info from "Intro to ACRN Configuration" doc and "Build ACRN from Source" doc
- Clarify why you need config files, difference between scenario vs. launch VM settings
- Updates are intended to reflect v2.6 code

Signed-off-by: Amy Reyes <amy.reyes@intel.com>
This commit is contained in:
Amy Reyes 2021-09-22 19:12:07 -07:00 committed by David Kinder
parent 6700a510be
commit 0ac609b5d8
15 changed files with 762 additions and 482 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/develop.rst
View File

@ -52,7 +52,11 @@ Configuration and Tools
:maxdepth: 1 :maxdepth: 1
tutorials/acrn_configuration_tool tutorials/acrn_configuration_tool
tutorials/board_inspector_tool
tutorials/acrn_configurator_tool
reference/config-options reference/config-options
reference/config-options-launch
reference/hv-make-options
user-guides/hv-parameters user-guides/hv-parameters
user-guides/kernel-parameters user-guides/kernel-parameters
user-guides/acrn-shell user-guides/acrn-shell

4
doc/getting-started/getting-started.rst
View File

@ -172,6 +172,8 @@ To set up the ACRN build environment on the development computer:
cd acrn-kernel cd acrn-kernel
git checkout release_2.6 git checkout release_2.6
.. _gsg-board-setup:
.. rst-class:: numbered-step .. rst-class:: numbered-step
Prepare the Target and Generate a Board Configuration File Prepare the Target and Generate a Board Configuration File
@ -382,6 +384,8 @@ Generate a Board Configuration File
cp $disk/my_board.xml ~/acrn-work cp $disk/my_board.xml ~/acrn-work
sudo umount $disk sudo umount $disk
.. _gsg-dev-setup:
.. rst-class:: numbered-step .. rst-class:: numbered-step
Generate a Scenario Configuration File and Launch Script Generate a Scenario Configuration File and Launch Script

4
doc/getting-started/overview_dev.rst
View File

@ -196,7 +196,7 @@ The tool generates a board configuration file specific to your hardware.
settings or PCI ports, you must generate a new board configuration file. settings or PCI ports, you must generate a new board configuration file.
The :ref:`gsg` provides step-by-step instructions for using the tool. For more The :ref:`gsg` provides step-by-step instructions for using the tool. For more
information about the tool, see :ref:`acrn_config_workflow`. information about the tool, see :ref:`board_inspector_tool`.
.. _overview_dev_config_editor: .. _overview_dev_config_editor:
@ -252,7 +252,7 @@ successful, the tool generates your custom launch script.
the parameters manually. See :ref:`acrn_config_data`. the parameters manually. See :ref:`acrn_config_data`.
The :ref:`gsg` walks you through a simple example of using the tool. For more The :ref:`gsg` walks you through a simple example of using the tool. For more
information about the tool, see :ref:`acrn_config_tool_ui`. information about the tool, see :ref:`acrn_configurator_tool`.
|icon_host| Step 5: Build ACRN |icon_host| Step 5: Build ACRN
****************************** ******************************

103
doc/reference/config-options-launch.rst Normal file
View File

@ -0,0 +1,103 @@
.. _launch-config-options:
Launch Configuration Options
##############################
As explained in :ref:`acrn_configuration_tool`, launch configuration files
define post-launched User VM settings. This document describes these option settings.
``uos``:
Specify the User VM with its relative ID to Service VM by the ``id``
attribute.
``uos_type``:
Specify the User VM type, such as ``CLEARLINUX``, ``ANDROID``, ``ALIOS``,
``PREEMPT-RT LINUX``, ``GENERIC LINUX``, ``WINDOWS``, ``YOCTO``, ``UBUNTU``,
``ZEPHYR`` or ``VXWORKS``.
``rtos_type``:
Specify the User VM Real-time capability: Soft RT, Hard RT, or none of them.
``mem_size``:
Specify the User VM memory size in megabytes.
``gvt_args``:
GVT arguments for the VM. Set it to ``gvtd`` for GVT-d, otherwise it's
for GVT-g arguments. The GVT-g input format:
``low_gm_size high_gm_size fence_sz``,
The recommendation is ``64 448 8``. Leave it blank to disable the GVT.
``vbootloader``:
Virtual bootloader type; currently only supports OVMF.
``vuart0``:
Specify whether the device model emulates the vUART0(vCOM1); refer to
:ref:`vuart_config` for details. If set to ``Enable``, the vUART0 is
emulated by the device model; if set to ``Disable``, the vUART0 is
emulated by the hypervisor if it is configured in the scenario XML.
``poweroff_channel``:
Specify whether the User VM power off channel is through the IOC,
power button, or vUART.
``allow_trigger_s5``:
Allow VM to trigger s5 shutdown flow, this flag works with
``poweroff_channel``
``vuart1(pty)`` and ``vuart1(tty)`` only.
``enable_ptm``:
Enable the Precision Timing Measurement (PTM) feature.
``usb_xhci``:
USB xHCI mediator configuration. Input format:
``bus#-port#[:bus#-port#: ...]``, e.g.: ``1-2:2-4``.
Refer to :ref:`usb_virtualization` for details.
``shm_regions``:
List of shared memory regions for inter-VM communication.
``shm_region`` (a child node of ``shm_regions``):
configure the shared memory regions for current VM, input format:
``hv:/<;shm name>; (or dm:/<shm_name>;), <;shm size in MB>;``. Refer
to :ref:`ivshmem-hld` for details.
``console_vuart``:
Enable a PCI-based console vUART. Refer to :ref:`vuart_config` for details.
``communication_vuarts``:
List of PCI-based communication vUARTs. Refer to :ref:`vuart_config` for
details.
``communication_vuart`` (a child node of ``communication_vuarts``):
Enable a PCI-based communication vUART with its ID. Refer to
:ref:`vuart_config` for details.
``passthrough_devices``:
Select the passthrough device from the lspci list. Currently we support:
``usb_xdci``, ``audio``, ``audio_codec``, ``ipu``, ``ipu_i2c``,
``cse``, ``wifi``, ``bluetooth``, ``sd_card``,
``ethernet``, ``sata``, and ``nvme``.
``network`` (a child node of ``virtio_devices``):
The virtio network device setting.
Input format: ``tap_name,[vhost],[mac=XX:XX:XX:XX:XX:XX]``.
``block`` (a child node of ``virtio_devices``):
The virtio block device setting.
Input format: ``[blk partition:][img path]`` e.g.: ``/dev/sda3:./a/b.img``.
``console`` (a child node of ``virtio_devices``):
The virtio console device setting.
Input format:
``[@]stdio|tty|pty|sock:portname[=portpath][,[@]stdio|tty|pty:portname[=portpath]]``.
``cpu_affinity``:
List of pCPU that this VM's vCPUs are pinned to.
.. note::
The ``configurable`` and ``readonly`` attributes are used to mark
whether the item is configurable for users. When ``configurable="n"``
and ``readonly="y"``, the item is not configurable from the web
interface. When ``configurable="n"``, the item does not appear on the
interface.

2
doc/reference/hardware.rst
View File

@ -108,7 +108,7 @@ For general instructions setting up ACRN on supported hardware platforms, visit
If an XML file is not provided by project ACRN for your board, we recommend you If an XML file is not provided by project ACRN for your board, we recommend you
use the board inspector tool to generate an XML file specifically for your board. use the board inspector tool to generate an XML file specifically for your board.
Refer to the :ref:`acrn_configuration_tool` for more details on using the board inspector Refer to :ref:`board_inspector_tool` for more details on using the board inspector
tool. tool.

199
doc/reference/hv-make-options.rst Normal file
View File

@ -0,0 +1,199 @@
.. _hypervisor-make-options:
Hypervisor Makefile Options
###########################
The ACRN hypervisor source code provides a makefile to build the ACRN
hypervisor binary and associated components.
Assuming that you are at the top level of the ``acrn-hypervisor`` directory,
you can run the ``make`` command to start the build. See :ref:`acrn_configuration_tool` for information about required input files.
Build Options
*************
The following table shows ACRN-specific command-line options:
.. list-table::
:widths: 33 77
:header-rows: 1
* - Option
- Description
* - ``BOARD``
- Required. Path to the board configuration file.
* - ``SCENARIO``
- Required. Path to the scenario configuration file.
* - ``RELEASE``
- Optional. Build a release version or a debug version. Valid values
are ``y`` for release version or ``n`` for debug version. (Default
is ``n``.)
* - ``hypervisor``
- Optional. Build the hypervisor only.
* - ``devicemodel``
- Optional. Build the Device Model only.
* - ``tools``
- Optional. Build the tools only.
* - ``O``
- Optional. Path to the directory where the built files will be stored.
(Default is the ``build`` directory.)
Example of a command to build the debug version:
.. code-block:: none
make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/industry.xml
Example of a command to build the release version:
.. code-block:: none
make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/industry.xml RELEASE=y
Example of a command to build the release version (hypervisor only):
.. code-block:: none
make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/industry.xml RELEASE=y hypervisor
Example of a command to build the release version of the Device Model and tools:
.. code-block:: none
make RELEASE=y devicemodel tools
Example of a command to put the built files in the specified directory
(``build-nuc``):
.. code-block:: none
make O=build-nuc BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/industry.xml
ACRN uses XML files to summarize board characteristics and scenario settings.
The ``BOARD`` and ``SCENARIO`` variables accept board/scenario names as well
as paths to XML files. When board/scenario names are given, the build system
searches for XML files with the same names under ``misc/config_tools/data/``.
When paths (absolute or relative) to the XML files are given, the build system
uses the files pointed at. If relative paths are used, they are considered
relative to the current working directory.
.. _acrn_makefile_targets:
Makefile Targets for Configuration
***********************************
ACRN source also includes the following makefile targets to aid customization.
.. list-table::
:widths: 33 77
: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.
Example of ``hvshowconfig`` to query the board, scenario, and build
type of an existing build:
.. code-block:: none
$ make BOARD=tgl-rvp SCENARIO=hybrid_rt hypervisor
...
$ make hvshowconfig
Build directory: /path/to/acrn-hypervisor/build/hypervisor
This build directory is configured with the settings below.
- BOARD = tgl-rvp
- SCENARIO = hybrid_rt
- RELEASE = n
Example of ``hvdefconfig`` to generate the configuration files in the
build directory, followed by an example of editing one of the configuration
files manually (``scenario.xml``) and then building the hypervisor:
.. code-block:: none
make BOARD=nuc7i7dnb SCENARIO=industry hvdefconfig
vim build/hypervisor/.scenario.xml
#(Modify the XML file per your needs)
make
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 configuration files can be changed manually, we recommend
you use the :ref:`ACRN configurator tool <acrn_configurator_tool>`, which
provides valid options and descriptions of the configuration entries.
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.
Example of how to use ``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
Example of 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
...

2
doc/release_notes/release_notes_2.5.rst
View File

@ -91,7 +91,7 @@ installed by executing the following command:
sudo pip3 install lxml sudo pip3 install lxml
.. note:: .. note::
Refer to :ref:`acrn_config_workflow` for a complete list of tools required to Refer to :ref:`gsg` for a complete list of tools required to
run the board inspector. run the board inspector.
With the prerequisites done, copy the entire board inspector folder from With the prerequisites done, copy the entire board inspector folder from

583
doc/tutorials/acrn_configuration_tool.rst
View File

@ -9,25 +9,24 @@ well as configure hypervisor capabilities and provision VMs.
ACRN configuration consists of the following key components. ACRN configuration consists of the following key components.
- Configuration data saved as XML files. * Configuration data saved as XML files.
- A configuration toolset that helps users to generate and edit configuration * A configuration toolset that helps users to generate and edit configuration
data. The toolset includes: data. The toolset includes:
- A **board inspector** that collects board-specific information on target - **Board inspector**: Collects board-specific information on target
machines. machines.
- A **configuration editor** that lets you edit configuration data via a web-based UI. - **ACRN configurator**: Enables you to edit configuration data via a
web-based UI.
The following sections introduce the concepts and tools of ACRN configuration The following sections introduce the concepts and tools of ACRN configuration
from the aspects below. from the aspects below.
- :ref:`acrn_config_types` introduces the objectives and main contents of * :ref:`acrn_config_types` introduces the objectives and main contents of
different types of configuration data. different types of configuration data.
- :ref:`acrn_config_workflow` overviews the steps to customize ACRN * :ref:`acrn_config_workflow` overviews the steps to customize ACRN
configuration using the configuration toolset. configuration using the configuration toolset.
- :ref:`acrn_config_data` explains the location and format of configuration * :ref:`acrn_config_data` explains the location and format of configuration
data saved as XML files. data saved as XML files.
- :ref:`acrn_config_tool_ui` gives detailed instructions on using the
configuration editor.
.. _acrn_config_types: .. _acrn_config_types:
@ -35,232 +34,126 @@ 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 configuration data are saved in three XML files. The following sections briefly
type. describe the objectives and main contents of each file.
Board Configuration Board Configuration File
=================== ========================
The board configuration stores hardware-specific information extracted on the The board configuration file stores hardware-specific information extracted
target platform. It describes the capacity of hardware resources (such as from the target platform. Examples of information:
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.
The board configuration is scenario-neutral by nature. Thus, multiple scenario * Capacity of hardware resources (such as processors and memory)
* Platform power states
* Available devices
* BIOS versions
You need a board configuration file to create scenario configurations. The
board configuration is scenario-neutral by nature. Thus, multiple scenario
configurations can be based on the same board configuration. configurations can be based on the same board configuration.
Scenario Configuration You also need a board configuration file to build an ACRN hypervisor. The
====================== build process uses the file to build a hypervisor that can
initialize and manage the platform at runtime.
The scenario configuration defines a working scenario by configuring hypervisor Scenario Configuration File
capabilities and defining VM attributes and resources. You can specify the ===========================
following in scenario configuration.
- Hypervisor capabilities 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:
- Availability and settings of hypervisor features, such as debugging * Hypervisor capabilities
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
size.
- VM attributes and resources - Availability and settings of hypervisor features, such as debugging
facilities, scheduling algorithm, inter-VM shared memory (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
size.
- VM attributes, such as VM names. * VM attributes and resources
- Maximum number of VMs supported.
- Resources allocated to each VM, such as number of vCPUs, amount of guest
memory, and pass-through devices.
- Guest OS settings, such as boot protocol and guest kernel parameters.
- Settings of virtual devices, such as virtual UARTs.
For pre-launched VMs, the VM attributes and resources are exactly the amount of - VM attributes, such as VM names.
resource allocated to them. For post-launched VMs, the number of vCPUs define - Maximum number of VMs supported.
the upper limit the Service VM can allocate to them and settings of virtual - Resources allocated to each VM, such as number of vCPUs, amount of guest
devices still apply. Other resources are under the control of the Service VM and memory, and pass-through devices.
can be dynamically allocated to post-launched VMs. - User VM settings, such as boot protocol and VM OS kernel parameters.
- Settings of virtual devices, such as virtual UARTs.
The scenario configuration is used by ACRN configuration tool to reserve You need a scenario configuration file to build an ACRN hypervisor. The
sufficient memory for the hypervisor to manage the VMs at build time, as well as build process uses the file to build a hypervisor that can initialize its capabilities and set up the VMs at runtime.
by ACRN hypervisor to initialize its capabilities and set up the VMs at runtime.
Launch Configuration The scenario configuration defines User VMs as follows:
====================
The launch configuration defines the attributes and resources of a * For pre-launched User VMs, the scenario configuration defines all attributes
post-launched VM. The main contents are similar to the VM attributes and and resources (these VMs have static configurations by nature). The VM
resources in scenario configuration. The launch configuration is used to generate shell scripts that attributes and resources are exactly the amount
invoke ``acrn-dm`` to create post-launched VMs. Unlike board and scenario of resources allocated to them.
configurations used at build time or by ACRN hypervisor, launch
configuration are used dynamically in the Service VM. * 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.
.. _acrn_config_workflow: .. _acrn_config_workflow:
Using ACRN Configuration Toolset Using ACRN Configuration Toolset
******************************** ********************************
ACRN configuration toolset is provided to create and edit configuration The ACRN configuration toolset enables you to create
data. The toolset can be found in ``misc/config_tools``. and edit configuration data. The toolset consists of the following:
Here is the workflow to customize ACRN configurations using the configuration * :ref:`Board inspector tool <board_inspector_tool>`
toolset. * :ref:`ACRN configurator tool <acrn_configurator_tool>`
#. Get the board info. As introduced in :ref:`overview_dev`, configuration takes place at Steps 3 and 4 in the overall development process:
a. Set up a native Linux environment on the target board. Make sure the .. image:: ../getting-started/images/overview_flow.png
following tools are installed and the kernel boots with the following
command line options.
| **Native Linux requirement:** ACRN source also includes makefile targets to aid customization. See :ref:`hypervisor-make-options`.
| **Release:** Ubuntu 18.04+
| **Tools:** cpuid, rdmsr, lspci, lxml, dmidecode (optional)
| **Kernel cmdline:** "idle=nomwait intel_idle.max_cstate=0 intel_pstate=disable"
#. Copy the ``board_inspector`` directory into the target file system and then run the
``sudo python3 board_inspector.py $(BOARD)`` command.
#. A ``$(BOARD).xml`` that includes all needed hardware-specific information
is generated under the current working directory. Here, ``$(BOARD)`` is the
specified board name.
#. Customize your needs.
a. Copy ``$(BOARD).xml`` to the host development machine.
#. Run the ACRN configuration editor (available at
``misc/config_tools/config_app/acrn_configurator.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 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 validate
the input based on both the ``$(BOARD).xml`` and ``$(SCENARIO).xml`` and then
export settings to your ``$(LAUNCH).xml``.
.. note:: Refer to :ref:`acrn_config_tool_ui` for more details on
the configuration editor.
#. Build with your XML files. Refer to :ref:`gsg` to build
the ACRN hypervisor with your XML files on the host machine.
#. Deploy VMs and run ACRN hypervisor on the target board.
.. figure:: images/offline_tools_workflow.png
:align: center
Configuration Workflow
.. _acrn_makefile_targets:
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_config_data:
ACRN Configuration Data ACRN Configuration Data
*********************** ***********************
ACRN configuration data are saved in three XML files: ``board``, ``scenario``, 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.
and ``launch`` XML. The ``board`` XML contains board configuration and is
generated by the board inspector on the target machine. The ``scenario`` and
``launch`` XMLs, containing scenario and launch configurations respectively, can
be customized by using the configuration editor. End users can load their own
configurations by importing customized XMLs or by saving the configurations by
exporting XMLs.
The predefined XMLs provided by ACRN are located in the ``misc/config_tools/data/`` ACRN source code offers predefined XMLs in the ``misc/config_tools/data/``
directory of the ``acrn-hypervisor`` repo. directory of the ``acrn-hypervisor`` repo.
Board XML Format Board XML Format
================ ================
The board XML has an ``acrn-config`` root element and a ``board`` attribute: The board XML has an ``acrn-config`` root element and a
``board`` attribute:
.. code-block:: xml .. code-block:: xml
<acrn-config board="BOARD"> <acrn-config board="BOARD">
Board XML files are input to the configuration editor and the build system, and are not The ``board`` attribute defines the board name and must match the
intended for end users to modify. ``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 Scenario XML Format
=================== ===================
@ -272,292 +165,32 @@ The scenario XML has an ``acrn-config`` root element as well as ``board`` and
<acrn-config board="BOARD" scenario="SCENARIO"> <acrn-config board="BOARD" scenario="SCENARIO">
See :ref:`scenario-config-options` for a full explanation of available scenario The ``board`` attribute specifies the board name and must match the ``board``
XML elements. Users are recommended to tweak the configuration data by using attribute in the board configuration file.
ACRN configuration editor.
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 Launch XML Format
================= =================
The launch XML has an ``acrn-config`` root element as well as ``board``, The launch XML has an ``acrn-config`` root element as well as
``scenario`` and ``uos_launcher`` attributes: ``board``, ``scenario`` and ``uos_launcher`` attributes:
.. code-block:: xml .. code-block:: xml
<acrn-config board="BOARD" scenario="SCENARIO" uos_launcher="UOS_NUMBER"> <acrn-config board="BOARD" scenario="SCENARIO" uos_launcher="UOS_NUMBER">
Attributes of the ``uos_launcher`` specify the number of User VMs that the The ``board`` attribute specifies the board name and must match the ``board``
current scenario has: attribute in the board configuration file and the scenario configuration file.
``uos``: The ``scenario`` attribute specifies the scenario name and must match the
Specify the User VM with its relative ID to Service VM by the ``id`` attribute. ``scenario`` attribute in the scenario configuration file.
``uos_type``: The ``uos_launcher`` attribute specifies the number of post-launched User VMs
Specify the User VM type, such as ``CLEARLINUX``, ``ANDROID``, ``ALIOS``, in a scenario.
``PREEMPT-RT LINUX``, ``GENERIC LINUX``, ``WINDOWS``, ``YOCTO``, ``UBUNTU``,
``ZEPHYR`` or ``VXWORKS``.
``rtos_type``: See :ref:`launch-config-options` for a full explanation of available launch
Specify the User VM Real-time capability: Soft RT, Hard RT, or none of them. XML elements.
``mem_size``:
Specify the User VM memory size in megabytes.
``gvt_args``:
GVT arguments for the VM. Set it to ``gvtd`` for GVT-d.
Leave it blank to disable the GVT.
``vbootloader``:
Virtual bootloader type; currently only supports OVMF.
``vuart0``:
Specify whether the device model emulates the vUART0(vCOM1); refer to
:ref:`vuart_config` for details. If set to ``Enable``, the vUART0 is
emulated by the device model; if set to ``Disable``, the vUART0 is
emulated by the hypervisor if it is configured in the scenario XML.
``poweroff_channel``:
Specify whether the User VM power off channel is through the IOC,
power button, or vUART.
``allow_trigger_s5``:
Allow VM to trigger s5 shutdown flow, this flag works with ``poweroff_channel``
``vuart1(pty)`` and ``vuart1(tty)`` only.
``enable_ptm``:
Enable the Precision Timing Measurement (PTM) feature.
``usb_xhci``:
USB xHCI mediator configuration. Input format:
``bus#-port#[:bus#-port#: ...]``, e.g.: ``1-2:2-4``.
Refer to :ref:`usb_virtualization` for details.
``shm_regions``:
List of shared memory regions for inter-VM communication.
``shm_region`` (a child node of ``shm_regions``):
configure the shared memory regions for current VM, input format:
``hv:/<;shm name>; (or dm:/<shm_name>;), <;shm size in MB>;``. Refer to :ref:`ivshmem-hld` for details.
``console_vuart``:
Enable a PCI-based console vUART. Refer to :ref:`vuart_config` for details.
``communication_vuarts``:
List of PCI-based communication vUARTs. Refer to :ref:`vuart_config` for details.
``communication_vuart`` (a child node of ``communication_vuarts``):
Enable a PCI-based communication vUART with its ID. Refer to :ref:`vuart_config` for details.
``passthrough_devices``:
Select the passthrough device from the lspci list. Currently we support:
``usb_xdci``, ``audio``, ``audio_codec``, ``ipu``, ``ipu_i2c``,
``cse``, ``wifi``, ``bluetooth``, ``sd_card``,
``ethernet``, ``sata``, and ``nvme``.
``network`` (a child node of ``virtio_devices``):
The virtio network device setting.
Input format: ``tap_name,[vhost],[mac=XX:XX:XX:XX:XX:XX]``.
``block`` (a child node of ``virtio_devices``):
The virtio block device setting.
Input format: ``[blk partition:][img path]`` e.g.: ``/dev/sda3:./a/b.img``.
``console`` (a child node of ``virtio_devices``):
The virtio console device setting.
Input format:
``[@]stdio|tty|pty|sock:portname[=portpath][,[@]stdio|tty|pty:portname[=portpath]]``.
``input`` (a child node of ``virtio_devices``):
The virtio input device setting.
Input format: ``/dev/input/eventX[,serial]``.
``cpu_affinity``:
List of pCPU that this VM's vCPUs are pinned to.
.. note::
The ``configurable`` and ``readonly`` attributes are used to mark
whether the item is configurable for users. When ``configurable="n"``
and ``readonly="y"``, the item is not configurable from the web
interface. When ``configurable="n"``, the item does not appear on the
interface.
.. _acrn_config_tool_ui:
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 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
- dynamically creates a new launch configuration and adds or deletes User VM
settings in it
Prerequisites
=============
- Clone the ACRN hypervisor repo
.. code-block:: bash
$ git clone https://github.com/projectacrn/acrn-hypervisor
- Install ACRN configuration editor dependencies:
.. code-block:: bash
$ cd ~/acrn-hypervisor/misc/config_tools/config_app
$ sudo pip3 install -r requirements
Instructions
============
#. Launch the ACRN configuration editor:
.. code-block:: bash
$ python3 acrn_configurator.py
#. Open a browser and navigate to the website
`<http://127.0.0.1:5001/>`_ automatically, or you may need to visit this
website manually. Make sure you can connect to open network from browser
because the editor needs to download some JavaScript files.
.. note:: The ACRN configuration editor is supported on Chrome, Firefox,
and Microsoft Edge. Do not use Internet Explorer.
The website is shown below:
.. figure:: images/config_app_main_menu.png
:align: center
:name: ACRN config tool main menu
#. Set the board info:
a. Click **Import Board info**.
.. figure:: images/click_import_board_info_button.png
:align: center
#. Upload the board XML you have generated from the ACRN board inspector.
#. After board XML is uploaded, you will see the board name from the
Board info list. Select the board name to be configured.
.. figure:: images/select_board_info.png
:align: center
#. Load or create the scenario configuration by selecting among the following:
- Choose a scenario from the **Scenario Setting** menu that lists all
user-defined scenarios for the board you selected in the previous step.
- Click the **Create a new scenario** from the **Scenario Setting** menu to
dynamically create a new scenario configuration for the current board.
- Click the **Load a default scenario** from the **Scenario Setting** menu,
and then select one default scenario configuration to load a predefined
scenario XML for the current board.
The default scenario XMLs are located at
``misc/config_tools/data/[board]/``. You can edit the scenario name when
creating or loading a scenario. If the current scenario name is duplicated
with an existing scenario setting name, rename the current scenario name or
overwrite the existing one after the confirmation message.
.. figure:: images/choose_scenario.png
:align: center
Note that you can also use a customized scenario XML by clicking **Import
XML**. The configuration editor automatically directs to the new scenario
XML once the import is complete.
#. The configurable items display after one scenario is created, loaded,
or selected. Following is an industry scenario:
.. figure:: images/configure_scenario.png
:align: center
- You can edit these items directly in the text boxes, or you can choose
single or even multiple items from the drop-down list.
- Read-only items are marked as gray.
- Hover the mouse cursor over the item to display the description.
#. Dynamically add or delete VMs:
- Click **Add a VM below** in one VM setting, and then select one VM type
to add a new VM under the current VM.
- Click **Remove this VM** in one VM setting to remove the current VM for
the scenario setting.
When one VM is added or removed in the scenario, the configuration editor
reassigns the VM IDs for the remaining VMs by the order of Pre-launched VMs,
Service VMs, and Post-launched VMs.
.. figure:: images/configure_vm_add.png
:align: center
#. Click **Export XML** to save the scenario XML; you can rename it in the
pop-up model.
.. note::
Save the customized scenario XML to a specific folder by inputting the
absolute path to this folder in the **Scenario XML Path** field. If you
don't specify a path, the scenario xml file will be saved to
default folder: ``acrn-hypervisor/../user_config/[board]/``.
Before saving the scenario XML, the configuration editor validates the
configurable items. If errors exist, the configuration editor lists all
incorrectly configured items and shows the errors as below:
.. figure:: images/err_acrn_configuration.png
:align: center
After the scenario is saved, the page automatically directs to the saved
scenario XMLs. Delete the configured scenario by clicking **Export XML** -> **Remove**.
The **Launch Setting** is quite similar to the **Scenario Setting**:
#. Upload board XML or select one board as the current board.
#. Load or create one launch configuration by selecting among the following:
- Click **Create a new launch script** from the **Launch Setting** menu.
- Click **Load a default launch script** from the **Launch Setting** menu.
- Select one launch XML from the menu.
- Import a local launch XML by clicking **Import XML**.
#. Select one scenario for the current launch configuration from the **Select
Scenario** drop-down box.
#. Configure the items for the current launch configuration.
#. Add or remove User VM (UOS) launch scripts:
- Add a UOS launch script by clicking **Configure an UOS below** for the
current launch configuration.
- Remove a UOS launch script by clicking **Remove this VM** for the
current launch configuration.
#. Save the current launch configuration to the ``user_config`` XML folder by
clicking **Export XML**. The configuration editor validates the current
configuration and lists all incorrectly configured items.
#. Click **Generate Launch Script** to save the current launch configuration and
then generate the launch script.
.. figure:: images/generate_launch_script.png
:align: center

216
doc/tutorials/acrn_configurator_tool.rst Normal file
View File

@ -0,0 +1,216 @@
.. _acrn_configurator_tool:
ACRN Configurator Tool
######################
This guide describes all features and uses of the tool.
About the ACRN Configurator Tool
*********************************
The ACRN configurator tool ``acrn_configurator.py`` provides a web-based
user interface to help you customize your
:ref:`ACRN configuration <acrn_configuration_tool>`. Capabilities:
- reads board information from the specified board configuration file
- provides a GUI to help you configure and validate scenario and
launch configuration files
- generates launch scripts for the specified post-launched User VMs
- dynamically creates a new scenario configuration and adds or deletes VM
settings in it
- dynamically creates a new launch configuration and adds or deletes User VM
settings in it
The tool guides you to configure ACRN in a particular order, due to
dependencies among the different types of configuration files. Here's an
overview of what to expect:
#. Import the board configuration file that you generated via the
:ref:`board inspector tool <board_inspector_tool>`.
#. Customize your scenario configuration file by defining hypervisor and
VM settings that will be used to build the ACRN hypervisor.
#. If your scenario has post-launched User VMs, customize launch scripts
that the Service VM will use to create the VMs
and allocate resources to them dynamically at runtime.
Customizing launch scripts involves these steps:
a. Configure settings for all post-launched User VMs in your scenario
and save the configuration in a launch configuration file.
#. Generate the launch scripts. The ACRN configurator creates one
launch script for each VM defined in the launch configuration file.
Generate a Scenario Configuration File and Launch Scripts
*********************************************************
The following steps describe all options in the ACRN configurator for generating a custom scenario configuration file and launch scripts.
#. Make sure the development computer is set up and ready to launch the ACRN
configurator, according to :ref:`gsg-dev-setup` in the Getting Started Guide.
#. Launch the ACRN configurator. This example assumes the tool is in the
``~/acrn-work/`` directory. Feel free to modify the command as needed.
.. code-block:: bash
python3 ~/acrn-work/acrn-hypervisor/misc/config_tools/config_app/acrn_configurator.py
#. Your web browser should open the website `<http://127.0.0.1:5001/>`_
automatically, or you may need to visit this website manually. The ACRN
configurator is supported on Chrome and Firefox.
#. Click the **Import Board info** button and browse to your board
configuration file. After the file is uploaded, make sure the board name
is selected in the **Board info** drop-down list and the board information
appears.
#. Start the scenario configuration process by selecting an option from the
**Scenario Setting** menu on the top banner of the UI or by importing a
scenario configuration file via the **Import XML** button. The 4 options
are described below:
* Click **Create a new scenario** from the **Scenario Setting** menu to
dynamically create a new scenario configuration for the current board.
* Click **Load a default scenario** from the **Scenario Setting** menu to
select a :ref:`predefined scenario configuration <usage-scenarios>`.
* Click the **Scenario Setting** menu and select a scenario from the list
under **scenario setting list**.
.. image:: images/choose_scenario.png
:align: center
* Click the **Import XML** button to import a customized scenario
configuration file.
The file must be one that was written for the current board. Any mismatch
in the board name and the one found in the scenario configuration file you
are trying to import will lead to an error message.
#. When the scenario configuration file is available for editing, the
configurable items appear below the **Scenario Setting** row. You may
need to scroll down to see them. Example:
.. image:: images/configure_scenario.png
:align: center
* You can edit these items directly in the text boxes, or you can choose
single or even multiple items from the drop-down list.
* Read-only items are marked as gray.
* Hover the mouse cursor over the item to see the description.
#. Add or delete VMs:
* Click **Add a VM below** in a VM’s settings, and then select a VM type
to add a new VM under the current VM.
* Click **Remove this VM** in a VM’s settings to remove the VM from the
scenario.
When a VM is added or removed, the configurator reassigns the VM IDs for
the remaining VMs by the order of pre-launched User VMs, Service VM, and
post-launched User VMs.
.. image:: images/configure_vm_add.png
:align: center
#. Click **Export XML** to save the scenario configuration file. A dialog box
appears, enabling you to save the file to a specific folder by inputting the
absolute path to this folder. If you don’t specify a path, the file will be
saved to the default folder:
 ``acrn-hypervisor/../user_config/<board name>``.
Before saving the scenario configuration file, the configurator validates
the configurable items. If errors exist, the configurator lists all
incorrectly configured items and shows the errors. Example:
.. image:: images/err_acrn_configuration.png
:align: center
After the scenario is saved, the page automatically displays the saved scenario configuration file.
#. To delete a scenario configuration file, click **Export XML** > **Remove**.
The configurator will delete the loaded file, even if you change the name of
the file in the dialog box.
#. If your scenario has post-launched User VMs, continue to the next step
to create launch scripts for those VMs. If your scenario doesn't have
post-launched User VMs, you can skip to the final step to close the tool.
#. Start the launch script configuration process by
selecting an option from the **Launch Setting** menu on the top banner of
the UI or by importing a launch configuration file via the **Import XML**
button. The 4 options are described below:
* Click **Create a new launch script** from the **Launch Setting** menu to
dynamically create a new launch configuration for the current board.
* Click **Load a default launch script** from the **Launch Setting** menu to
select a predefined launch configuration.
* Click the **Launch Setting** menu and select a launch configuration
from the list under **launch setting list**.
.. image:: images/choose_launch.png
:align: center
* Click the **Import XML** button to import a customized launch
configuration file.
#. Select a scenario for the current launch configuration from the
 **Select Scenario** drop-down box.
#. When the launch configuration file is available for editing, the
configurable items appear below the **Launch Setting** row. You may need
to scroll down to see them. Example:
.. image:: images/configure_launch.png
:align: center
* You can edit these items directly in the text boxes, or you can choose
single or even multiple items from the drop-down list.
* Read-only items are marked as gray.
* Hover the mouse cursor over the item to see the description.
#. Add or remove User VM (UOS) launch scripts:
* Click **Configure an UOS below** to add a User VM launch script.
* Click **Remove this VM** to remove a User VM launch script.
.. image:: images/configure_launch_add.png
:align: center
#. Click **Export XML** to save the launch configuration file. A dialog box
appears, enabling you to save the file to a specific folder by inputting the
absolute path to this folder. If you don’t specify a path, the file will
be saved to the default folder:
 ``acrn-hypervisor/../user_config/<board name>``.
Before saving the launch configuration file, the configurator validates the
configurable items. If errors exist, the configurator lists all incorrectly
configured items and shows the errors.
#. To delete a launch configuration file, click **Export XML** > **Remove**.
The configurator will delete the loaded file, even if you change the name of
the file in the dialog box.
#. Click **Generate Launch Script** to save the current launch configuration
and then generate a launch script for each VM defined in the launch
configuration.
.. image:: images/generate_launch_script.png
:align: center
#. Confirm that the launch scripts appear in the
``<board name>/output`` directory.
#. When you are done using the tool, close the browser and press
:kbd:`CTRL` + :kbd:`C` to terminate the
``acrn_configurator.py`` program running in the terminal window.

121
doc/tutorials/board_inspector_tool.rst Normal file
View File

@ -0,0 +1,121 @@
.. _board_inspector_tool:
Board Inspector Tool
####################
This guide describes all features and uses of the tool.
About the Board Inspector Tool
******************************
The board inspector tool ``board_inspector.py`` enables you to generate a board
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>`.
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.
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.
#. Load the ``msr`` driver, used by the board inspector:
.. code-block:: bash
sudo modprobe msr
#. 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
name. Feel free to modify the commands as needed.
.. code-block:: bash
cd ~/acrn-work/board_inspector/
sudo python3 board_inspector.py my_board
Upon success, the tool displays the following message:
.. code-block:: console
PTCT table has been saved to PTCT successfully!
#. Confirm that the board configuration file ``my_board.xml`` was generated in
the current directory.
.. _board_inspector_cl:
Command-Line Options
********************
You can configure the board inspector via command-line options. Running the
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
positional arguments:
board_name the name of the board that runs the ACRN hypervisor
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
--check-device-status
filter out devices whose _STA object evaluates to 0
Details about certain arguments:
.. list-table::
:widths: 33 77
:header-rows: 1
* - Argument
- Details
* - ``board_name``
- Required. The board name is used as the file name of the board
configuration file and is placed inside the file for other tools to read.
* - ``--out``
- Optional. Specify a file path where the board configuration file will be
saved (example: ``~/acrn_work``). If only a filename is provided in this
option, the board inspector will generate the file in the current
directory.
* - ``--basic``
- Optional. By default, the board inspector parses the ACPI namespace when
generating board configuration files. This option provides a way to
disable ACPI namespace parsing in case the parsing blocks the generation
of board configuration files.
* - ``--loglevel``
- Optional. Choose log level, e.g., info, warning or error.
(Default is warning.)
* - ``--check-device-status``
- Optional. On some boards, the device status (reported by the _STA
object) returns 0 while the device object is still useful for
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.

2
doc/tutorials/cpu_sharing.rst
View File

@ -130,7 +130,7 @@ Scheduler configuration
* The scheduler used at runtime is defined in the scenario XML file * The scheduler used at runtime is defined in the scenario XML file
via the :option:`hv.FEATURES.SCHEDULER` option. The default scheduler via the :option:`hv.FEATURES.SCHEDULER` option. The default scheduler
is **SCHED_BVT**. Use the :ref:`ACRN configuration tool <acrn_configuration_tool>` is **SCHED_BVT**. Use the :ref:`ACRN configurator tool <acrn_configurator_tool>`
if you want to change this scenario option value. if you want to change this scenario option value.

BIN
doc/tutorials/images/choose_launch.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

BIN
doc/tutorials/images/configure_launch.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 66 KiB

BIN
doc/tutorials/images/configure_launch_add.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 66 KiB

4
doc/tutorials/nvmx_virtualization.rst
View File

@ -113,10 +113,10 @@ ACRN only supports enabling the nested virtualization feature on the Service VM,
VMs. VMs.
The nested virtualization feature is disabled by default in ACRN. You can The nested virtualization feature is disabled by default in ACRN. You can
enable it using the :ref:`Use the ACRN Configuration Editor <acrn_config_tool_ui>` enable it using the :ref:`ACRN configurator tool <acrn_configurator_tool>`
with these settings: with these settings:
.. note:: Normally you'd use the configuration tool GUI to edit the scenario XML file. .. note:: Normally you'd use the configurator tool GUI to edit the scenario XML file.
The tool wasn't updated in time for the v2.5 release, so you'll need to manually edit The tool wasn't updated in time for the v2.5 release, so you'll need to manually edit
the ACRN scenario XML configuration file to edit the ``SCHEDULER``, ``NVMX_ENABLED``, the ACRN scenario XML configuration file to edit the ``SCHEDULER``, ``NVMX_ENABLED``,
``pcpu_id`` , ``guest_flags``, ``legacy_vuart``, and ``console_vuart`` settings for ``pcpu_id`` , ``guest_flags``, ``legacy_vuart``, and ``console_vuart`` settings for