mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-05-02 13:44:00 +00:00
5083aba379
Update material from PR #3559 with review and clarity edits. Added review comments. Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
157 lines
5.5 KiB
ReStructuredText
157 lines
5.5 KiB
ReStructuredText
.. _acrn_configuration_tool:
|
|
|
|
ACRN Configuration Tool
|
|
#######################
|
|
|
|
.. note:: This document is under development and planned for the 1.3
|
|
release.
|
|
|
|
|
|
ACRN Configurations Introduction
|
|
********************************
|
|
There are three types of configurations in ACRN: Hypervisor,
|
|
Board, and VM. We'll explore each of these in the following sections.
|
|
|
|
Hypervisor configuration
|
|
========================
|
|
Hypervisor configuration selects a working scenario and target
|
|
board by configuring the hypervisor image features and capabilities such as
|
|
setting up the log and the serial port.
|
|
|
|
Hypervisor configuration is done using the ``Kconfig`` ``make
|
|
menuconfig`` mechanism. The configuration file is located at::
|
|
|
|
acrn-hypervisor/hypervisor/arch/x86/configs/Kconfig
|
|
|
|
A board-specific ``defconfig`` file, located at::
|
|
|
|
acrn-hypervisor/hypervisor/arch/x86/configs/$(BOARD)/$(BOARD).config
|
|
|
|
will be loaded first, as the default ``Kconfig`` for the specified board.
|
|
|
|
Board configuration
|
|
===================
|
|
The board configuration stores board-specific settings referenced by the
|
|
ACRN hypervisor. This includes *scenario-relevant* information such as
|
|
board settings, root device selection, and kernel cmdline, and
|
|
*scenario-irrelevant** hardware-specific information such as ACPI/PCI
|
|
and BDF information. The board configuration is organized as
|
|
``*.c/*.h`` files located at::
|
|
|
|
acrn-hypervisor/hypervisor/arch/x86/$(BOARD)/
|
|
|
|
VM configuration
|
|
=================
|
|
VM configuration includes *scenario-based* VM configuration
|
|
information, used to describe the characteristics and attributes for VMs
|
|
on each user scenario, and *launch script-based* VM configuration, where
|
|
parameters are passed to the device model to launch post-launched User
|
|
VMs.
|
|
|
|
Scenario based VM configurations are organized
|
|
as ``*.c/*.h`` files located at::
|
|
|
|
acrn-hypervisor/hypervisor/scenarios/$(SCENARIO)/
|
|
|
|
User VM launch script samples are located at::
|
|
|
|
acrn-hypervisor/devicemodel/samples/
|
|
|
|
Configuration tool workflow
|
|
***************************
|
|
|
|
Hypervisor configuration workflow
|
|
==================================
|
|
Hypervisor configuration is based on the ``Kconfig`` ``make menuconfig``
|
|
mechanism. You begin by creating a board specific ``defconfig`` file to
|
|
set up the default ``Kconfig`` values for the specified board.
|
|
Then you configure the hypervisor build options using the ``make
|
|
menuconfig`` graphical interface. The resulting ``.config`` file is
|
|
used by the ACRN build process to create a configured scenario- and
|
|
board-specific hypervisor image.
|
|
|
|
.. figure:: images/sample_of_defconfig.png
|
|
:align: center
|
|
|
|
defconfig file sample
|
|
|
|
.. figure:: images/GUI_of_menuconfig.png
|
|
:align: center
|
|
|
|
menuconfig interface sample
|
|
|
|
Please refer to the :ref:`getting-started-hypervisor-configuration` for
|
|
detailed steps.
|
|
|
|
Board and VM configuration workflow
|
|
===================================
|
|
Python offline tools are provided to configure Board and VM configurations.
|
|
The tool source folder is located at::
|
|
|
|
acrn-hypervisor/misc/acrn-config/
|
|
|
|
Here is the offline configuration tool workflow:
|
|
|
|
#. Get board info.
|
|
|
|
a. Set up native Linux environment on target board.
|
|
#. Copy ``target`` folder into target file system and then run
|
|
``sudo python3 board_parser.py $(BOARD)`` command.
|
|
#. A $(BOARD).xml that includes all needed hardware-specific information
|
|
will be generated in the ``./out/`` folder. (Here ``$(BOARD)`` is the
|
|
specified board name)
|
|
|
|
| **Native Linux requirement:**
|
|
| **Release:** Ubuntu 18.04+ or Clear Linux 30210+
|
|
| **Tools:** cpuid, rdmsr, lspci, dmidecode (optional)
|
|
| **Kernel cmdline:** "idle=nomwait intel_idle.max_cstate=0 intel_pstate=disable"
|
|
|
|
#. Customize your needs.
|
|
|
|
.. note:: **[TO BE DEVELOPED]**
|
|
The tool in this step is still under development. Until then,
|
|
you can input settings by editing the target XML file manually.
|
|
|
|
a. Copy ``$(BOARD).xml`` to the host develop machine.
|
|
#. Run a UI based configuration tool on the host machine to input the
|
|
desired scenario settings. The tool will do a sanity check on the
|
|
input based on ``$(BOARD).xml`` and then generate a customized
|
|
scenario-based VM configurations in ``$(SCENARIO).xml``.
|
|
#. In the configuration tool UI, input the launch script parameters for the
|
|
post-launched User VM. The tool will sanity check the input based on
|
|
both ``$(BOARD).xml`` and ``$(SCENARIO).xml`` and then generate a launch
|
|
script-based VM configuration in ``$(LAUNCH_PARAM).xml``.
|
|
|
|
#. Auto generate code.
|
|
|
|
Python tools are used to generate configurations in patch format.
|
|
The patches will be applied to your local ``acrn-hypervisor`` git tree
|
|
automatically.
|
|
|
|
a. Generate a patch for the board-related configuration with::
|
|
|
|
cd misc/board_config
|
|
python3 board_cfg_gen.py --board $(BOARD).xml
|
|
|
|
#. **[TO BE DEVELOPED]** Generate a patch for scenario-based VM
|
|
configuration with::
|
|
|
|
cd misc/scenario_config
|
|
python3 scenario_cfg_gen.py --board $(BOARD).xml --scenario
|
|
|
|
#. **[TO BE DEVELOPED]** Generate the launch script for the specified
|
|
post-launch User VM with::
|
|
|
|
cd misc/launch_config
|
|
python3 launch_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml --launch $(LAUNCH_PARAM).xml$
|
|
|
|
#. Re-build the ACRN hypervisor. Please refer to the
|
|
:ref:`getting-started-building` to re-build ACRN hypervisor on host machine.
|
|
|
|
#. Deploy VMs and run ACRN hypervisor on target board.
|
|
|
|
.. figure:: images/offline_tools_workflow.png
|
|
:align: center
|
|
|
|
offline tool workflow
|