diff --git a/doc/develop.rst b/doc/develop.rst index 5576a28ea..04c260d44 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -23,6 +23,7 @@ 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 new file mode 100644 index 000000000..1eb26e25c --- /dev/null +++ b/doc/tutorials/acrn_configuration_tool.rst @@ -0,0 +1,134 @@ +.. _acrn_configuration_tool: + +ACRN Configuration Tool +####################### + +ACRN Configurations Introduction +******************************** +There are three types of configurations in ACRN: Hypervisor configurations, +Board configurations and VM configurations. + +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 configurations is configured by ``Kconfig`` mechanism. +The configuration file is located at:: + + acrn-hypervisor/hypervisor/arch/x86/configs/Kconfig + +A defconfig file which located at:: + + acrn-hypervisor/hypervisor/arch/x86/configs/$(BOARD)/$(BOARD).config + +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:: + + acrn-hypervisor/hypervisor/arch/x86/$(BOARD)/ + +VM configurations +================= +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:: + + acrn-hypervisor/hypervisor/scenarios/$(SCENARIO)/ + +User VM launch script samples are located at:: + + acrn-hypervisor/devicemodel/samples/ + +Configuration Tool Working Flow +******************************* + +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. + +.. figure:: images/sample_of_defconfig.png + :align: center + + Sample of defconfig file + +.. figure:: images/GUI_of_menuconfig.png + :align: center + + GUI of menuconfig + +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:: + + acrn-hypervisor/misc/acrn-config/ + +Below is offline configure tool working flow: + +#. Get board info. + + a. Setup 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) + + | **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" + +#. 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. + + 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``; + +#. 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; + +#. Re-build 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 diff --git a/doc/tutorials/images/GUI_of_menuconfig.png b/doc/tutorials/images/GUI_of_menuconfig.png new file mode 100644 index 000000000..330f963ec Binary files /dev/null and b/doc/tutorials/images/GUI_of_menuconfig.png differ diff --git a/doc/tutorials/images/offline_tools_workflow.png b/doc/tutorials/images/offline_tools_workflow.png new file mode 100644 index 000000000..bb487d4a3 Binary files /dev/null and b/doc/tutorials/images/offline_tools_workflow.png differ diff --git a/doc/tutorials/images/sample_of_defconfig.png b/doc/tutorials/images/sample_of_defconfig.png new file mode 100644 index 000000000..050131902 Binary files /dev/null and b/doc/tutorials/images/sample_of_defconfig.png differ