doc: review edits for config tool doc
Update material from PR #3559 with review and clarity edits. Added review comments. Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder
David Kinder
parent
ede5988587
commit
5083aba379
|
|
@ -7,7 +7,10 @@ Develop using ACRN
|
|||
Configuration Tools
|
||||
*******************
|
||||
|
||||
- Offline configuration Tool (under developmemnt)
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
tutorials/acrn_configuration_tool
|
||||
|
||||
Configuration Tutorials
|
||||
***********************
|
||||
|
|
@ -23,7 +26,6 @@ Configuration Tutorials
|
|||
tutorials/using_partition_mode_on_up2
|
||||
tutorials/using_sdc2_mode_on_nuc
|
||||
tutorials/using_hybrid_mode_on_nuc
|
||||
tutorials/acrn_configuration_tool
|
||||
|
||||
User VM Tutorials
|
||||
*****************
|
||||
|
|
|
|||
|
|
@ -3,46 +3,53 @@
|
|||
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 configurations,
|
||||
Board configurations and VM configurations.
|
||||
There are three types of configurations in ACRN: Hypervisor,
|
||||
Board, and VM. We'll explore each of these in the following sections.
|
||||
|
||||
Hypervisor configurations
|
||||
=========================
|
||||
Hypervisor configurations is used to select working scenario and target board,
|
||||
configure features and capabilities, set up log and serial port etc. to build
|
||||
differential hypervisor image for different board.
|
||||
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 configurations is configured by ``Kconfig`` mechanism.
|
||||
The configuration file is located at::
|
||||
Hypervisor configuration is done using the ``Kconfig`` ``make
|
||||
menuconfig`` mechanism. The configuration file is located at::
|
||||
|
||||
acrn-hypervisor/hypervisor/arch/x86/configs/Kconfig
|
||||
|
||||
A defconfig file which located at::
|
||||
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.
|
||||
will be loaded first, as the default ``Kconfig`` for the specified board.
|
||||
|
||||
Board configurations
|
||||
====================
|
||||
Board configurations is used to store board related configurations that referenced
|
||||
by ACRN hypervisor, including scenario irrelevant information and scenario relevant
|
||||
information. Scenario irrelevant information is hardware specific, like ACPI/PCI
|
||||
BDF info/.etc. Scenario relevant information is board settings in each scenario
|
||||
like root device selection/kernel cmdline. The board configuration is organized
|
||||
as ``*.c/*.h`` file and located at::
|
||||
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 configurations
|
||||
VM configuration
|
||||
=================
|
||||
VM configurations includes scenario based VM configurations and launch script
|
||||
based VM configurations. The former one is used to describe characteristic/attributes
|
||||
of the VM on each user scenario, another is launch script parameters for device model
|
||||
to launch post-launched User VM. Scenario based VM configurations is organized
|
||||
as ``*.c/*.h`` file and located at::
|
||||
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)/
|
||||
|
||||
|
|
@ -50,45 +57,49 @@ User VM launch script samples are located at::
|
|||
|
||||
acrn-hypervisor/devicemodel/samples/
|
||||
|
||||
Configuration Tool Working Flow
|
||||
*******************************
|
||||
Configuration tool workflow
|
||||
***************************
|
||||
|
||||
Kconfig
|
||||
=======
|
||||
Hypervisor configurations is based on ``Kconfig`` ``make menuconfig`` mechanism,
|
||||
user could configure it in menuconfig GUI by using ``make menuconfig``
|
||||
command to generate the needed ``.config`` file for hypervisor build usage.
|
||||
Before running ``make menuconfig``, user need to create board specific ``defconfig``
|
||||
to setup default ``Kconfig`` value for the specified board.
|
||||
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
|
||||
|
||||
Sample of defconfig file
|
||||
defconfig file sample
|
||||
|
||||
.. figure:: images/GUI_of_menuconfig.png
|
||||
:align: center
|
||||
|
||||
GUI of menuconfig
|
||||
menuconfig interface sample
|
||||
|
||||
Please refer to the :ref:`getting-started-hypervisor-configuration` for detailed steps.
|
||||
Please refer to the :ref:`getting-started-hypervisor-configuration` for
|
||||
detailed steps.
|
||||
|
||||
Offline configure tool
|
||||
======================
|
||||
For Board configurations and VM configurations, an offline configure tool is
|
||||
designed to configure them. The tool source folder is located at::
|
||||
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/
|
||||
|
||||
Below is offline configure tool working flow:
|
||||
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 which includes all needed hardware specific information
|
||||
will be generated at ``./out/`` folder. (Here $(BOARD) is the specified board name)
|
||||
#. 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+
|
||||
|
|
@ -98,37 +109,48 @@ Below is offline configure tool working flow:
|
|||
#. Customize your needs.
|
||||
|
||||
.. note:: **[TO BE DEVELOPED]**
|
||||
The tool in this step is still under development, before its readiness user
|
||||
could input the setting by editing the target XML file manually.
|
||||
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 host develop machine;
|
||||
#. Run a UI based configure tool on host machine to input the expected scenario settings,
|
||||
the tool will do sanity check on the input based on ``$(BOARD).xml`` and then generate
|
||||
customized scenario based VM configurations in ``$(SCENARIO).xml``;
|
||||
#. In the UI of configure tool, continue to input launch script parameter for
|
||||
post-launched User VM. The tool will check the input based on both ``$(BOARD).xml``
|
||||
and ``$(SCENARIO).xml`` and then generate launch script based VM configurations in
|
||||
``$(LAUNCH_PARAM).xml``;
|
||||
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.
|
||||
There are three python tools will be used to generate configurations in patch format.
|
||||
The patches will be applied to ``acrn-hypervisor`` git tree automatically.
|
||||
|
||||
a. Run ``python3 board_cfg_gen.py --board $(BOARD).xml`` under ``misc/board_config``
|
||||
folder, it will generate patch for board related configurations;
|
||||
#. **[TO BE DEVELOPED]** Run ``python3 scenario_cfg_gen.py --board $(BOARD).xml --scenario
|
||||
$(SCENARIO).xml`` under ``misc/scenario_config`` folder, it will generate patch
|
||||
for scenario based VM configurations;
|
||||
#. **[TO BE DEVELOPED]** Run ``python3 launch_cfg_gen.py --board $(BOARD).xml
|
||||
--scenario $(SCENARIO).xml --launch $(LAUNCH_PARAM).xml$`` under ``misc/launch_config``
|
||||
folder, it will generate launch script for the specified post-launch User VM;
|
||||
Python tools are used to generate configurations in patch format.
|
||||
The patches will be applied to your local ``acrn-hypervisor`` git tree
|
||||
automatically.
|
||||
|
||||
#. Re-build ACRN hypervisor. Please refer to the :ref:`getting-started-building`
|
||||
to re-build ACRN hypervisor on host machine;
|
||||
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 working flow
|
||||
offline tool workflow
|
||||
|
|
|
|||
Loading…
Reference in New Issue