doc: update ACRN configuration tool document

- Remove the TBD parts;
- Add configuration tool UI app instructions;
- Update "Build from Source" for generating the hypervisor via configuration tool.

Signed-off-by: lirui34 <ruix.li@intel.com>

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
 <https://www.intel.com/content/www/us/en/design/products-and-solutions/technologies/slim-bootloader/overview.html>`_)
 hypervisor.
 
+As mentioned in :ref:`ACRN Configuration Tool <vm_config_workflow>`,
+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.
 

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
+
+   <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
 ***************************
 
@@ -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 <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%