acrn-hypervisor/doc/tutorials/acrn_configuration_tool.rst

.. _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

   <acrn-config board=”BOARD”>

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

   <acrn-config board=”BOARD” scenario=”SCENARIO”>

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

   <acrn-config board="BOARD" scenario="SCENARIO" uos_launcher="UOS_NUMBER">

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 <getting-started-building>` 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:
   `<http://127.0.0.1:5001/>`_ 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%