.. _acrn_configuration_tool: ACRN Configuration Tool ####################### The ACRN configuration tool is designed for System Integrators / Tier 1s 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 web interface and configure the hypervisor from XML files at build time. Introduction ************ ACRN includes three types of configurations: Hypervisor, Board, and VM. Each are discussed in the following sections. Hypervisor configuration ======================== The 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. The hypervisor configuration uses 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 is loaded first; it is 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 the kernel cmdline. It also includes **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 that is used to describe the characteristics and attributes for VMs on each user scenario. It also includes **launch script-based** VM configuration information, 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 *********************** The ACRN configuration includes three kinds of XMLs for acrn-config usage: ``board``, ``scenario``, and ``launch`` XML. All scenario-irrelevant hardware-specific information for the board configuration is stored in the ``board`` XML. The XML is generated by ``misc/acrn-config/target/board_parser.py`` which runs on the target board. The scenario-relevant board and scenario-based VM configurations are stored in the ``scenario`` XML. The launch script-based VM configuration is stored in the ``launch`` XML. These two XMLs can be customized by using the web inteface tool at ``misc/acrn-config/config-app/app.py``. End users can load their own configurations by importing customized XMLs or by saving the configurations by exporting XMLs. Board XML format ================ The board XML has an ``acrn-config`` root element and a ``board`` attribute: .. code-block:: xml As an input for the ``acrn-config`` tool, end users do not need to care about the format of board XML and should not modify it. Scenario XML format =================== The scenario XML has an ``acrn-config`` root element as well as ``board`` and ``scenario`` attributes: .. code-block:: xml Additional scenario XML 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 the hypervisor console command: vm_list. ``uuid``: UUID of the VM. It is for internal use and is not configurable. ``guest_flags``: Select all applicable flags for the VM. ``vcpu_affinity``: vCPU affinity map. Each vCPU will pin to the selected pCPU ID. A different vCPU cannot pin to the same pCPU. ``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. Refer to the 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 the hypervisor code. ``kern_type``: Specify the kernel image type so that the hypervisor can load it correctly. Currently supports KERNEL_BZIMAGE and KERNEL_ZEPHYR. ``kern_mod``: The tag for the kernel image that acts as a multiboot module; it must exactly match the module tag in the GRUB multiboot cmdline. ``bootargs`` under parent of ``os_config``: For internal use and is not configurable. Specify the kernel boot arguments in bootargs under the parent of board_private. ``vuart``: Specify the vuart (A.K.A COM) with the vUART ID by its "id" attribute. Refer to :ref:`vuart_config` for detailed vUART settings. ``type`` under parent of ``vuart``: vUART (A.K.A COM) type, currently only supports the 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, specify which target VM the current VM connects to. ``target_uart_id``: Target vUART ID that vCOM2 connects to. ``pci_dev_num``: PCI devices number of the VM; it is hard-coded for each scenario so it is not configurable for now. ``pci_devs``: PCI devices list of the VM; it is hard-coded for each scenario so it is not configurable for now. ``board_private``: Stores scenario-relevant board configuration. ``rootfs``: rootfs for the Linux kernel. ``console``: ttyS console for the Linux kernel. ``bootargs`` under parent of ``board_private``: Specify kernel boot arguments. Launch XML format ================= The launch XML has an ``acrn-config`` root element as well as ``board``, ``scenario`` and ``uos_launcher`` attributes: .. code-block:: xml Attributes of the ``uos_launcher`` specify the number of User VMs that the current scenario has: ``uos``: Specify the User VM with its relative ID to Service VM by the "id" attribute. ``uos_type``: Specify the User VM type, such as CLEARLINUX, ANDROID, or VXWORKS. ``rtos_type``: Specify the User VM Realtime capability: Soft RT, Hard RT, or none of them. ``cpu_num``: Specify the max cpu number for the VM. ``mem_size``: Specify the User VM memory size in Mbyte. ``gvt_args``: GVT argument for the VM. ``vbootloader``: Virtual bootloader type; currently only supports OVMF. ``rootfs_dev``: The device where User VM rootfs located. ``rootfs_img``: User VM rootfs image file including path. ``console_type``: Specify whether the User VM console is virtio or vUART; refer to :ref:`vuart_config` for details. ``poweroff_channel``: Specify whether the User VM power off channel is through the IOC, Powerbutton, or vUART. ``passthrough_devices``: Select the passthrough device from the lspci list; currently we support: usb_xdci, audio, audio_codec, ipu, ipu_i2c, cse, wifi, Bluetooth, sd_card, ethernet, wifi, sata, and nvme. .. note:: The ``configurable`` and ``readonly`` attributes are used to mark whether the items is configurable for users. When ``configurable=”0”`` and ``readonly=”true”``, the item is not configurable from the web interface. When ``configurable=“0”``. the item does not appear on the interface. Configuration tool workflow *************************** Hypervisor configuration workflow ================================== The hypervisor configuration is based on the ``Kconfig`` ``make menuconfig`` mechanism. Begin by creating a board-specific ``defconfig`` file to set up the default ``Kconfig`` values for the specified board. Next, 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 Refer to :ref:`getting-started-hypervisor-configuration` for detailed configuration 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 the board info. a. Set up a native Linux environment on the target board. #. Copy the ``target`` folder into the target file system and then run the ``sudo python3 board_parser.py $(BOARD)`` command. #. A $(BOARD).xml that includes all needed hardware-specific information is 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 development machine. #. Run the ``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 the $(BOARD).xml. The customized settings can 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 the $(BOARD).xml and $(SCENARIO).xml and then export settings to your $(LAUNCH).xml. #. The user defined XMLs can be imported by acrn-config for modification. .. note:: Refer to :ref:`acrn_config_tool_ui` for more details on the configuration tool UI. 3. Auto generate the code. Python tools are used to generate configurations in patch format. The patches are applied to your local ``acrn-hypervisor`` git tree automatically. a. Generate a patch for the board-related configuration:: cd misc/board_config python3 board_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml Note that this can also be done by clicking **Generate Board SRC** in the acrn-config UI. #. Generate a patch for scenario-based VM configuration:: cd misc/scenario_config python3 scenario_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml Note that this can also be done by clicking **Generate Scenario SRC** in the acrn-config UI. #. Generate the launch script for the specified post-launch User VM:: cd misc/launch_config python3 launch_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml --launch $(LAUNCH).xml Note that this can also be done by clicking **Generate Launch Script** in the acrn-config UI. #. Re-build the ACRN hypervisor. Refer to :ref:`getting-started-building` to re-build the ACRN hypervisor on the host machine. #. Deploy VMs and run ACRN hypervisor on the target board. .. figure:: images/offline_tools_workflow.png :align: center Offline tool workflow .. _acrn_config_tool_ui: Use the ACRN configuration app ****************************** The ACRN configuration app is a web user interface application that performs the following: - reads board info - configures and validates scenario settings - automatically generates patches for board-related configurations and scenario-based VM configurations - configures and validates launch settings - generates 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 the ACRN hypervisor repo to your host. - Install ACRN configuration app dependencies: .. code-block:: none $ cd ~/acrn-hypervisor/misc/acrn-config/config_app $ sudo pip3 install -r requirements Instructions ============ #. Launch the ACRN configuration app: .. code-block:: none $ python3 app.py #. Open a browser and navigate to the website ``_ automatically, or you may need to visit this website manually. 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, and MS Edge, do not use IE. The website is shown below: .. figure:: images/config_app_main_menu.png :align: center :name: ACRN config tool main menu #. Set the board info: a. Click **Import Board info**. .. figure:: images/click_import_board_info_button.png :align: center #. Upload the board info you have generated from the ACRN config tool. #. After board info is 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 #. Choose a scenario from the **Scenario Setting** menu which lists all the scenarios, including the efault scenarios and the user-defined scenarios for the board you selected in the previous step. The scenario configuration xmls are located at ``acrn-hypervisor/misc/xmls/config-xmls/[board]/``. .. figure:: images/choose_scenario.png :align: center Note that you can also use a customized scenario xml by clicking **Import**. The configuration app automatically directs to the new scenario xml once the import is complete. #. The configurable items display after one scenario is selected. Here is the example of "SDC" scenario: .. figure:: images/configure_scenario.png :align: center - You can edit these items directly in the text boxes, cor you can 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** 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 errors exist, the configuration app lists all wrong configurable items and shows the errors as below: .. figure:: images/err_acrn_configuration.png :align: center After the scenario is saved, the page automatically directs to the saved scenario xmls. You can delete the configured scenario by clicking **Export** -> **Remove**. #. Click **Generate Board SRC** to save the 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 the current scenario setting and then generate a patch for the scenario-based VM configuration scenario source codes in ``acrn-hypervisor/hypervisor/scenarios/[scenario]/``. The **Launch Setting** is quite similar to the **Scenario Setting**: #. Upload board info or select one board as the current board. #. Import your local launch setting xml by clicking **Import** or selecting one launch setting xml from the menu. #. Select one scenario for the current launch setting from the **Select Scenario** drop down box. #. Configure the items for the current launch setting. #. Save the current launch setting to the user-defined xml files by clicking **Export**. The configuration app validates the current configuration and lists all wrong configurable items and shows errors. #. Click **Generate Launch Script** to save the current launch setting and then generate the launch script. .. figure:: images/generate_launch_script.png :align: center