diff --git a/doc/tutorials/acrn_configuration_tool.rst b/doc/tutorials/acrn_configuration_tool.rst index 5ba1677b5..b5e4cd09c 100644 --- a/doc/tutorials/acrn_configuration_tool.rst +++ b/doc/tutorials/acrn_configuration_tool.rst @@ -22,14 +22,11 @@ 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/ - -A board-specific ``defconfig`` file, located at:: - - acrn-hypervisor/hypervisor/arch/x86/configs/$(BOARD).config +menuconfig`` mechanism. The configuration file is located in the +``acrn-hypervisor/hypervisor/arch/x86/configs/`` folder. +The board-specific ``defconfig`` file, +``acrn-hypervisor/hypervisor/arch/x86/configs/$(BOARD).config`` is loaded first; it is the default ``Kconfig`` for the specified board. Board configuration @@ -40,9 +37,8 @@ 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/configs/$(BOARD)/ +``*.c/*.h`` files located in the +``acrn-hypervisor/hypervisor/arch/x86/configs/$(BOARD)/`` folder. VM configuration ================= @@ -53,113 +49,146 @@ 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:: +Scenario based VM configurations are organized as ``*.c/*.h`` files +located in the ``acrn-hypervisor/hypervisor/scenarios/$(SCENARIO)/`` +folder. - acrn-hypervisor/hypervisor/scenarios/$(SCENARIO)/ - -User VM launch script samples are located at:: - - acrn-hypervisor/devicemodel/samples/ +User VM launch script samples are located in the +``acrn-hypervisor/devicemodel/samples/`` folder. 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 +The ACRN configuration includes three kinds of XML files 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 interface 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 located at: -acrn-hypervisor/misc/acrn-config/xmls/board-xmls +The board XMLs are located in the +``acrn-hypervisor/misc/acrn-config/xmls/board-xmls/`` folder. 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. +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 located at: -acrn-hypervisor/misc/acrn-config/xmls/config-xmls -The scenario XML has an ``acrn-config`` root element as well as ``board`` and ``scenario`` attributes: +The scenario XMLs are located in the +``acrn-hypervisor/misc/acrn-config/xmls/config-xmls/`` folder. 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. +``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. +``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. +``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. +``uuid``: + UUID of the VM. It is for internal use and is not configurable. -``guest_flags``: Select all applicable flags for the VM. +``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. +``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. +``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. +``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. +``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. +``start_hpa``: + The start physical address in host for the VM. -``size`` under parent of ``memory``: The memory size in Bytes 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. +``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_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. +``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. +``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. +``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. +``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. +``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. +``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_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. +``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_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. +``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. +``board_private``: + Stores scenario-relevant board configuration. -``rootfs``: rootfs for the Linux kernel. +``rootfs``: + rootfs for the Linux kernel. -``console``: ttyS console for the Linux kernel. +``console``: + ttyS console for the Linux kernel. -``bootargs`` under parent of ``board_private``: Specify kernel boot arguments. +``bootargs`` under parent of ``board_private``: + Specify kernel boot arguments. Launch XML format ================= -The launch XML located at: -acrn-hypervisor/misc/acrn-config/xmls/config-xmls +The launch XMLs are located in the +``acrn-hypervisor/misc/acrn-config/xmls/config-xmls/`` folder. The launch XML has an ``acrn-config`` root element as well as ``board``, ``scenario`` and ``uos_launcher`` attributes: @@ -169,31 +198,48 @@ The launch XML has an ``acrn-config`` root element as well as 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``: + 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. +``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. +``rtos_type``: + Specify the User VM Realtime capability: Soft RT, Hard RT, or none of them. -``mem_size``: Specify the User VM memory size in Mbyte. +``mem_size``: + Specify the User VM memory size in Mbyte. -``gvt_args``: GVT argument for the VM. +``gvt_args``: + GVT argument for the VM. -``vbootloader``: Virtual bootloader type; currently only supports OVMF. +``vbootloader``: + Virtual bootloader type; currently only supports OVMF. -``rootfs_dev``: The device where User VM rootfs located. +``rootfs_dev``: + The device where User VM rootfs located. -``rootfs_img``: User VM rootfs image file including path. +``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. +``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. +``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. +``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. + 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 *************************** @@ -229,9 +275,7 @@ 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/ +The tool source folder is ``acrn-hypervisor/misc/acrn-config/``. Here is the offline configuration tool workflow: @@ -252,11 +296,18 @@ Here is the offline configuration tool workflow: #. 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. + #. 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 + .. note:: Refer to :ref:`acrn_config_tool_ui` for more details on the configuration tool UI. 3. Auto generate the code. @@ -305,10 +356,11 @@ 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 + scenario-based VM configurations - configures and validates launch settings - generates launch scripts for the specified post-launched User VMs. @@ -318,7 +370,7 @@ Prerequisites .. _get acrn repo guide: https://projectacrn.github.io/latest/getting-started/building-from-source.html#get-the-acrn-hypervisor-source-code -- Clone acrn-hypervisor : +- Clone acrn-hypervisor: .. code-block:: none @@ -342,9 +394,12 @@ Instructions $ 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. + ``_ 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. + .. note:: The ACRN configuration app is supported on Chrome, Firefox, + and MS Edge. Do not use IE. The website is shown below: @@ -361,13 +416,14 @@ Instructions #. 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. + #. 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 + including the default 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]/``. @@ -395,7 +451,9 @@ Instructions .. 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: + 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 @@ -421,10 +479,11 @@ The **Launch Setting** is quite similar to the **Scenario Setting**: #. 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. +#. 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 -