diff --git a/doc/getting-started/building-from-source.rst b/doc/getting-started/building-from-source.rst index 98e0ed925..1049d4672 100644 --- a/doc/getting-started/building-from-source.rst +++ b/doc/getting-started/building-from-source.rst @@ -312,10 +312,23 @@ If you only need the hypervisor, then use this command: $ make -C hypervisor $ make -C misc/efi-stub HV_OBJDIR=$PWD/hypervisor/build EFI_OBJDIR=$PWD/hypervisor/build -The acrn.efi will be generated in directory: . /hypervisor/build/acrn.efi +The``acrn.efi`` will be generated in directory: ``./hypervisor/build/acrn.efi`` (`Slim bootloader `_) hypervisor. +As mentioned in :ref:`ACRN Configuration Tool `, +Board configuration and VM configuration could be imported from XML files. +If you want to build hypervisor with XML configuration files, please specify the +file location as follows: + +.. code-block:: none + + $ BOARD_FILE=/home/acrn-hypervisor/misc/acrn-config/xmls/board-xmls/apl-up2.xml + SCENARIO_FILE=/home/acrn-hypervisor/misc/acrn-config/xmls/config-xmls/apl-up2/sdc.xml FIRMWARE=uefi + +.. note:: The file path must be absolute path. Both of the ``BOARD`` and ``SCENARIO`` + parameters are not needed because the information could be got from XML. + Follow the same instructions to boot and test the images you created from your build. diff --git a/doc/tutorials/acrn_configuration_tool.rst b/doc/tutorials/acrn_configuration_tool.rst index f5ae1c0eb..4773a3189 100644 --- a/doc/tutorials/acrn_configuration_tool.rst +++ b/doc/tutorials/acrn_configuration_tool.rst @@ -2,10 +2,10 @@ ACRN Configuration Tool ####################### - -.. note:: This document is under development and planned for the 1.3 - release. - +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 ******************************** @@ -57,6 +57,111 @@ 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 *************************** @@ -83,6 +188,8 @@ board-specific hypervisor image. 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. @@ -108,19 +215,20 @@ Here is the offline configuration tool workflow: #. Customize your needs. - .. note:: **[TO BE DEVELOPED]** - 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 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``. + #. 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. 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``. + 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. @@ -128,22 +236,32 @@ Here is the offline configuration tool workflow: The patches will be applied to your local ``acrn-hypervisor`` git tree automatically. - a. Generate a patch for the board-related configuration with:: + 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 + python3 board_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml - #. **[TO BE DEVELOPED]** Generate a patch for scenario-based VM - configuration with:: + .. 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 + python3 scenario_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml - #. **[TO BE DEVELOPED]** Generate the launch script for the specified - post-launch User VM with:: + .. 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_PARAM).xml$ + 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. @@ -154,3 +272,140 @@ Here is the offline configuration tool workflow: :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% diff --git a/doc/tutorials/images/choose_scenario.png b/doc/tutorials/images/choose_scenario.png new file mode 100644 index 000000000..88c4e322c Binary files /dev/null and b/doc/tutorials/images/choose_scenario.png differ diff --git a/doc/tutorials/images/click_import_board_info_button.png b/doc/tutorials/images/click_import_board_info_button.png new file mode 100644 index 000000000..f19162390 Binary files /dev/null and b/doc/tutorials/images/click_import_board_info_button.png differ diff --git a/doc/tutorials/images/config_app_main_menu.png b/doc/tutorials/images/config_app_main_menu.png new file mode 100644 index 000000000..3033c08a5 Binary files /dev/null and b/doc/tutorials/images/config_app_main_menu.png differ diff --git a/doc/tutorials/images/configure_scenario.png b/doc/tutorials/images/configure_scenario.png new file mode 100644 index 000000000..9f50c6f86 Binary files /dev/null and b/doc/tutorials/images/configure_scenario.png differ diff --git a/doc/tutorials/images/err_acrn_configuration.png b/doc/tutorials/images/err_acrn_configuration.png new file mode 100644 index 000000000..37c94808c Binary files /dev/null and b/doc/tutorials/images/err_acrn_configuration.png differ diff --git a/doc/tutorials/images/generate_launch_script.png b/doc/tutorials/images/generate_launch_script.png new file mode 100644 index 000000000..23632a0d3 Binary files /dev/null and b/doc/tutorials/images/generate_launch_script.png differ diff --git a/doc/tutorials/images/select_board_info.png b/doc/tutorials/images/select_board_info.png new file mode 100644 index 000000000..6007892f3 Binary files /dev/null and b/doc/tutorials/images/select_board_info.png differ