diff --git a/doc/develop.rst b/doc/develop.rst index 04c260d44..64bb4b565 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -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 ***************** diff --git a/doc/tutorials/acrn_configuration_tool.rst b/doc/tutorials/acrn_configuration_tool.rst index 1eb26e25c..f5ae1c0eb 100644 --- a/doc/tutorials/acrn_configuration_tool.rst +++ b/doc/tutorials/acrn_configuration_tool.rst @@ -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,85 +57,100 @@ 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. 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 ``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 ClearLinux 30210+ - | **Tools:** cpuid, rdmsr, lspci, dmidecode(optional) - | **Kernel cmdline:** "idle=nomwait intel_idle.max_cstate=0 intel_pstate=disable" + | **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, 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 \ No newline at end of file + offline tool workflow