OrgACRN
/
acrn-hypervisor
mirror of https://github.com/projectacrn/acrn-hypervisor.git
1
0
Fork 0
Code Issues Releases Wiki Activity

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 2019-09-09 11:04:01 -07:00 committed by David Kinder
parent ede5988587
commit 5083aba379
2 changed files with 98 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/develop.rst
View File

@ -7,7 +7,10 @@ Develop using ACRN
Configuration Tools Configuration Tools
******************* *******************
- Offline configuration Tool (under developmemnt) .. toctree::
:maxdepth: 1
tutorials/acrn_configuration_tool
Configuration Tutorials Configuration Tutorials
*********************** ***********************
@ -23,7 +26,6 @@ Configuration Tutorials
tutorials/using_partition_mode_on_up2 tutorials/using_partition_mode_on_up2
tutorials/using_sdc2_mode_on_nuc tutorials/using_sdc2_mode_on_nuc
tutorials/using_hybrid_mode_on_nuc tutorials/using_hybrid_mode_on_nuc
tutorials/acrn_configuration_tool
User VM Tutorials User VM Tutorials
***************** *****************

166
doc/tutorials/acrn_configuration_tool.rst
View File

@ -3,46 +3,53 @@
ACRN Configuration Tool ACRN Configuration Tool
####################### #######################
.. note:: This document is under development and planned for the 1.3
release.
ACRN Configurations Introduction ACRN Configurations Introduction
******************************** ********************************
There are three types of configurations in ACRN: Hypervisor configurations, There are three types of configurations in ACRN: Hypervisor,
Board configurations and VM configurations. Board, and VM. We'll explore each of these in the following sections.
Hypervisor configurations Hypervisor configuration
========================= ========================
Hypervisor configurations is used to select working scenario and target board, Hypervisor configuration selects a working scenario and target
configure features and capabilities, set up log and serial port etc. to build board by configuring the hypervisor image features and capabilities such as
differential hypervisor image for different board. setting up the log and the serial port.
Hypervisor configurations is configured by ``Kconfig`` mechanism. Hypervisor configuration is done using the ``Kconfig`` ``make
The configuration file is located at:: menuconfig`` mechanism. The configuration file is located at::
acrn-hypervisor/hypervisor/arch/x86/configs/Kconfig 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 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 configuration
==================== ===================
Board configurations is used to store board related configurations that referenced The board configuration stores board-specific settings referenced by the
by ACRN hypervisor, including scenario irrelevant information and scenario relevant ACRN hypervisor. This includes *scenario-relevant* information such as
information. Scenario irrelevant information is hardware specific, like ACPI/PCI board settings, root device selection, and kernel cmdline, and
BDF info/.etc. Scenario relevant information is board settings in each scenario *scenario-irrelevant** hardware-specific information such as ACPI/PCI
like root device selection/kernel cmdline. The board configuration is organized and BDF information. The board configuration is organized as
as ``*.c/*.h`` file and located at:: ``*.c/*.h`` files located at::
acrn-hypervisor/hypervisor/arch/x86/$(BOARD)/ acrn-hypervisor/hypervisor/arch/x86/$(BOARD)/
VM configurations VM configuration
================= =================
VM configurations includes scenario based VM configurations and launch script VM configuration includes *scenario-based* VM configuration
based VM configurations. The former one is used to describe characteristic/attributes information, used to describe the characteristics and attributes for VMs
of the VM on each user scenario, another is launch script parameters for device model on each user scenario, and *launch script-based* VM configuration, where
to launch post-launched User VM. Scenario based VM configurations is organized parameters are passed to the device model to launch post-launched User
as ``*.c/*.h`` file and located at:: VMs.
Scenario based VM configurations are organized
as ``*.c/*.h`` files located at::
acrn-hypervisor/hypervisor/scenarios/$(SCENARIO)/ acrn-hypervisor/hypervisor/scenarios/$(SCENARIO)/
@ -50,85 +57,100 @@ User VM launch script samples are located at::
acrn-hypervisor/devicemodel/samples/ acrn-hypervisor/devicemodel/samples/
Configuration Tool Working Flow Configuration tool workflow
******************************* ***************************
Kconfig Hypervisor configuration workflow
======= ==================================
Hypervisor configurations is based on ``Kconfig`` ``make menuconfig`` mechanism, Hypervisor configuration is based on the ``Kconfig`` ``make menuconfig``
user could configure it in menuconfig GUI by using ``make menuconfig`` mechanism. You begin by creating a board specific ``defconfig`` file to
command to generate the needed ``.config`` file for hypervisor build usage. set up the default ``Kconfig`` values for the specified board.
Before running ``make menuconfig``, user need to create board specific ``defconfig`` Then you configure the hypervisor build options using the ``make
to setup default ``Kconfig`` value for the specified board. 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 .. figure:: images/sample_of_defconfig.png
:align: center :align: center
Sample of defconfig file defconfig file sample
.. figure:: images/GUI_of_menuconfig.png .. figure:: images/GUI_of_menuconfig.png
:align: center :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 Board and VM configuration workflow
====================== ===================================
For Board configurations and VM configurations, an offline configure tool is Python offline tools are provided to configure Board and VM configurations.
designed to configure them. The tool source folder is located at:: The tool source folder is located at::
acrn-hypervisor/misc/acrn-config/ acrn-hypervisor/misc/acrn-config/
Below is offline configure tool working flow: Here is the offline configuration tool workflow:
#. Get board info. #. Get board info.
a. Setup native Linux environment on target board. a. Set up native Linux environment on target board.
#. Copy ``target`` folder into target file system and then run #. Copy ``target`` folder into target file system and then run
``sudo python3 board_parser.py $(BOARD)`` command. ``sudo python3 board_parser.py $(BOARD)`` command.
#. A $(BOARD).xml which includes all needed hardware specific information #. A $(BOARD).xml that includes all needed hardware-specific information
will be generated at ``./out/`` folder. (Here $(BOARD) is the specified board name) will be generated in the ``./out/`` folder. (Here ``$(BOARD)`` is the
specified board name)
| **Native Linux requirement:** | **Native Linux requirement:**
| **Release:** Ubuntu 18.04+ or ClearLinux 30210+ | **Release:** Ubuntu 18.04+ or Clear Linux 30210+
| **Tools:** cpuid, rdmsr, lspci, dmidecode(optional) | **Tools:** cpuid, rdmsr, lspci, dmidecode (optional)
| **Kernel cmdline:** "idle=nomwait intel_idle.max_cstate=0 intel_pstate=disable" | **Kernel cmdline:** "idle=nomwait intel_idle.max_cstate=0 intel_pstate=disable"
#. Customize your needs. #. Customize your needs.
.. note:: **[TO BE DEVELOPED]** .. note:: **[TO BE DEVELOPED]**
The tool in this step is still under development, before its readiness user The tool in this step is still under development. Until then,
could input the setting by editing the target XML file manually. you can input settings by editing the target XML file manually.
a. Copy ``$(BOARD).xml`` to host develop machine; a. Copy ``$(BOARD).xml`` to the host develop machine.
#. Run a UI based configure tool on host machine to input the expected scenario settings, #. Run a UI based configuration tool on the host machine to input the
the tool will do sanity check on the input based on ``$(BOARD).xml`` and then generate desired scenario settings. The tool will do a sanity check on the
customized scenario based VM configurations in ``$(SCENARIO).xml``; input based on ``$(BOARD).xml`` and then generate a customized
#. In the UI of configure tool, continue to input launch script parameter for scenario-based VM configurations in ``$(SCENARIO).xml``.
post-launched User VM. The tool will check the input based on both ``$(BOARD).xml`` #. In the configuration tool UI, input the launch script parameters for the
and ``$(SCENARIO).xml`` and then generate launch script based VM configurations in post-launched User VM. The tool will sanity check the input based on
``$(LAUNCH_PARAM).xml``; both ``$(BOARD).xml`` and ``$(SCENARIO).xml`` and then generate a launch
script-based VM configuration in ``$(LAUNCH_PARAM).xml``.
#. Auto generate code. #. 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`` Python tools are used to generate configurations in patch format.
folder, it will generate patch for board related configurations; The patches will be applied to your local ``acrn-hypervisor`` git tree
#. **[TO BE DEVELOPED]** Run ``python3 scenario_cfg_gen.py --board $(BOARD).xml --scenario automatically.
$(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;
#. Re-build ACRN hypervisor. Please refer to the :ref:`getting-started-building` a. Generate a patch for the board-related configuration with::
to re-build ACRN hypervisor on host machine;
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. #. Deploy VMs and run ACRN hypervisor on target board.
.. figure:: images/offline_tools_workflow.png .. figure:: images/offline_tools_workflow.png
:align: center :align: center
offline tool working flow offline tool workflow