.. _acrn_configuration_tool: ACRN Configuration Tool ####################### ACRN configuration tool is designed for System Integrators / Tier1’s to customize ACRN to meet their own needs. It consists of two tools. The ``Kconfig`` tool and the ``acrn-config`` tool. The latter allows users to provision VMs via a WebUI and configure the hypervisor from XML files at build time. 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/ ACRN Configuration XMLs *********************** ACRN configuration introduced three kinds of XMLs for acrn-config usage: **board**, **scenario** and **launch** XML. All scenario-irrelevant hardware-specific information of Board configuration is stored in **board** XML. The XML is generated by ``misc/acrn-config/target/board_parser.py`` which shall be run on target board. The scenario-relevant Board configuration and scenario-based VM configuration are stored in **scenario** XML. The launch script-based VM configuration is stored in **launch** XML. These two XMLs could be customized with WebUI tool at ``misc/acrn-config/config-app/app.py``. End users could load their own configurations by importing customized XMLs or save the configurations by exporting XMLs. Board XML format ================ Board XML has a root element of ``acrn-config`` with attribute of **board**, i.e. .. code-block:: xml As an input for ``acrn-config`` tool, end users do not need to care about the format of board XML and should not modify it. Scenario XML format =================== Scenario XML has a root element of ``acrn-config`` with attributes of **board** and **scenario**, i.e. .. code-block:: xml Below is the usage of other elements: :``vm``: Specify the VM with VMID by its "id" attribute. :``load_order``: Specify the VM by its load order: PRE_LAUNCHED_VM, SOS_VM or POST_LAUNCHED_VM. :``name`` under parent of ``vm``: Specify the VM name which will be shown in hypervisor console command: vm_list. :``uuid``: UUID of the VM. It is for internal use and not configurable. :``guest_flags``: Select all applicable flags for the VM. :``size`` under parent of ``epc_section``: SGX EPC section base, must be page aligned. :``base`` under parent of ``epc_section``: SGX EPC section size in Bytes, must be page aligned. :``clos``: Class of Service for Cache Allocation Technology. Please refer SDM 17.19.2 for details and use with caution. :``start_hpa``: The start physical address in host for the VM. :``size`` under parent of ``memory``: The memory size in Bytes for the VM :``name`` under parent of ``os_config``: Specify the OS name of VM, currently it is not referenced by hypervisor code. :``kern_type``: Specify the kernel image type so that hypervisor could load it correctly. Currently support KERNEL_BZIMAGE and KERNEL_ZEPHYR. :``kern_mod``: The tag for kernel image which act as multiboot module, it must exactly match the module tag in GRUB multiboot cmdline. :``bootargs`` under parent of ``os_config``: It is for internal use and not configurable. Please specify the kernel boot arguments in bootargs under parent of board_private. :``vuart``: Specify the vuart(A.K.A COM) with vUART ID by its "id" attribute. Please refer :ref:`vuart_config` for detailed vUART setting. :``type`` under parent of ``vuart``: vUART(A.K.A COM) type, currently only support legacy PIO mode. :``base`` under parent of ``vuart``: vUART(A.K.A COM) enabling switch. Enable by exposing its COM_BASE(SOS_COM_BASE for Service VM), disable by returning INVALID_COM_BASE. :``irq`` under parent of ``vuart``: vCOM irq. :``target_vm_id``: COM2 is used for VM communications. When it is enabled, please specify which target VM that current VM connect to. :``target_uart_id``: target vUART ID that vCOM2 connect to. :``pci_dev_num``: pci devices number of the VM, it is hard-coded for each scenario so is not configurable for now. :``pci_devs``: PCI devices list of the VM, it is hard-coded for each scenario so is not configurable for now. :``board_private``: Stores scenario-relevant Board configuration. :``rootfs``: rootfs for Linux kernel. :``console``: ttyS console for Linux kernel :``bootargs`` under parent of ``board_private``: Specify kernel boot arguments. Launch XML format ================= Launch XML has a root element of ``acrn-config`` with attributes of **board**, **scenario** and **uos_launcher**, i.e. .. code-block:: xml Attribute of **uos_launcher** specified the number of User VM that current scenario has: :``uos``: Specify the User VM with its relative ID to Service VM by "id" attribute. :``uos_type``: Specify the User VM type, like CLEARLINUX, ANDROID, or VXWORKS :``rtos_type``: Specify User VM Realtime capability: Soft RT, Hard RT, or none of them. :``cpu_num``: Specify max cpu number for the VM. :``mem_size``: Specify User VM memory size in Mbyte. :``gvt_args``: GVT argument for the VM. :``vbootloader``: virtual bootloader type, currently only support OVMF. :``rootfs_dev``: Which device where User VM rootfs located. :``rootfs_img``: User VM rootfs image file including path. :``console_type``: Specify User VM console is virtio or vUART, please refer :ref:`vuart_config` for details. :``poweroff_channel``: Specify User VM power off channel is through IOC or Powerbutton or vUART. :``passthrough_devices``: select the passthrough device from lspci list, currently we support selection for usb_xdci, audio, audio_codec, ipu, ipu_i2c, cse, wifi, Bluetooth, sd_card, ethernet, wifi, sata and nvme. .. note:: Attribute of **configurable** and **readonly** are used to mark whether the items is configurable for user. When ``configurable=”0”`` and ``readonly=”true”``, the item is not configurable from WebUI. Particularly, the item would not be shown on UI when ``configurable=“0”``. 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. .. _vm_config_workflow: 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. a. Copy ``$(BOARD).xml`` to the host develop machine. #. Run ``misc/acrn-config/config-app/app.py`` tool on the host machine and import the ``$(BOARD).xml``, select your working scenario under **Scenario Setting** and input the desired scenario settings. The tool will do a sanity check on the input based on ``$(BOARD).xml``. The customized settings could be exported to your own ``$(SCENARIO).xml``. #. In the configuration tool UI, input the launch script parameters for the post-launched User VM under **Launch Setting**. The tool will sanity check the input based on both ``$(BOARD).xml`` and ``$(SCENARIO).xml`` and then export settings to your ``$(LAUNCH).xml``. #. The user defined XMLs could be imported by acrn-config for modification. .. note:: Please refer :ref:`acrn_config_tool_ui` for more details on the configuration tool UI. #. 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: .. code-block:: console cd misc/board_config python3 board_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml .. note:: This could be done by click **Generate Board SRC** in acrn-config UI. #. Generate a patch for scenario-based VM configuration with: .. code-block:: console cd misc/scenario_config python3 scenario_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml .. note:: This could be done by click **Generate Scenario SRC** in acrn-config UI. #. Generate the launch script for the specified post-launched User VM with: .. code-block:: console cd misc/launch_config python3 launch_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml --launch $(LAUNCH).xml$ .. note:: This could be done by click **Generate Launch Script** in acrn-config UI. #. 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 .. _acrn_config_tool_ui: How to use ACRN configuration app ********************************* ACRN configuration app is a web UI application to read board info, configure and validate scenario setting, automatically generate a patch for board related configuration, scenario-based VM configuration, configure and validate launch settings, generate the launch scripts for the specified post-launched User VMs. Prerequisites ============= .. _get acrn repo guide: https://projectacrn.github.io/latest/getting-started/building-from-source.html#get-the-acrn-hypervisor-source-code - Follow the :ref:`instruction ` to install the ACRN hypervisor dependencies and tools on your development host. - Follow the `get acrn repo guide`_ to download ACRN hypervisor repo to your host. - Install ACRN configuration app dependencies: .. code-block:: console $ cd ~/acrn-hypervisor/misc/acrn-config/config_app $ sudo pip3 install -r requirements How to use ACRN configuration app ================================= #. Launch ACRN configuration app: .. code-block:: console $ python3 app.py #. The browser should be launched and navigated to the website: ``_ automatically, or you may need to visit this website manually. .. note:: Make sure you can connect to open network from browser because the app needs to download some javascript files. .. note:: The ACRN configuration app is supported on Chrome, Firefox or MS Edge, do not use IE. The website as shown below: .. figure:: images/config_app_main_menu.png :align: center :scale: 70% :name: ACRN config tool main menu #. Set the board info: a. Click the button **Import Board info**. .. figure:: images/click_import_board_info_button.png :align: center :scale: 70% #. Upload the board info you have generated by ACRN config tool. #. After board info uploaded, you will see the board name from the Board info list, select the board name to be configured. .. figure:: images/select_board_info.png :align: center :scale: 70% #. Choose a scenario from the “Scenario Setting” menu which lists all the scenarios including default scenarios and user-defined scenarios for the board you selected in the previous step. The scenario configuration xmls are located in ``acrn-hypervisor/misc/xmls/config-xmls/[board]/``. .. figure:: images/choose_scenario.png :align: center :scale: 70% #. It is also allowed to use a customized scenario xml by clicking the Import button. The configuration app will automatically direct to the new scenario xml once the import is completed. #. The configurable items will be displayed after one scenario is selected. Here is the example of "SDC" scenario: .. figure:: images/configure_scenario.png :align: center :scale: 70% - You can edit those items directly in the text boxes, choose single or even multiple items from the drop down list. - Read-only items are marked as grey. - Hover the mouse pointer over the item to display the description. #. Click **Export** button to save the scenario xml, you can rename it in the pop-up modal. .. note:: All customized scenario xmls will be in user-defined groups which located in ``acrn-hypervisor/misc/xmls/config-xmls/[board]/user_defined/``. Before saving the scenario xml, the configuration app will validate the configurable items; If there are errors, the configuration app will list all wrong configurable items and show errors as below: .. figure:: images/err_acrn_configuration.png :align: center :scale: 70% After the scenario is saved, the page will automatically direct to the saved scenario xmls. You can delete the configured scenario by click button **Export** -> **Remove**. #. Click **Generate Board SRC** to save current scenario setting and then generate a patch for the board-related configuration source codes in ``acrn-hypervisor/hypervisor/arch/x86/configs/[board]/``. #. Click **Generate Scenario SRC** to save current scenario setting and then generate a patch for scenario-based VM configuration scenario source codes in ``acrn-hypervisor/hypervisor/scenarios/[scenario]/``. #. **Launch Setting** is quite similar with **Scenario Setting**: a. Upload board info or selecting one board as current board. #. Import your local launch setting xml by clicking button **Import** or selecting one launch setting xml from menu. #. Select one scenario for current launch setting from the drop down box **Select Scenario**. #. Configure the items for current launch setting. #. Save current launch setting to user defined xml files by clicking the button **Export**. The configuration app will validate current configuration and will list all wrong configurable items and show errors. #. Click the button **Generate Launch Script** to save current launch setting and then generate launch script. .. figure:: images/generate_launch_script.png :align: center :scale: 70%