github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-27 15:56:54 +00:00
Code Issues Projects Releases Wiki Activity

doc: review edits for acrn_configuration_tool

Browse Source 
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2019-11-08 09:59:28 -08:00 committed by David Kinder
parent 0d86951e46
commit 38abceb761
1 changed files with 149 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

233
doc/tutorials/acrn_configuration_tool.rst
View File

@ -22,14 +22,11 @@ board by configuring the hypervisor image features and capabilities such as
setting up the log and the serial port. setting up the log and the serial port.
The hypervisor configuration uses the ``Kconfig`` ``make The hypervisor configuration uses the ``Kconfig`` ``make
menuconfig`` mechanism. The configuration file is located at:: menuconfig`` mechanism. The configuration file is located in the
``acrn-hypervisor/hypervisor/arch/x86/configs/`` folder.
acrn-hypervisor/hypervisor/arch/x86/configs/
A board-specific ``defconfig`` file, located at::
acrn-hypervisor/hypervisor/arch/x86/configs/$(BOARD).config
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. is loaded first; it is the default ``Kconfig`` for the specified board.
Board configuration 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 board settings, root device selection, and the kernel cmdline. It also includes
**scenario-irrelevant** hardware-specific information such as ACPI/PCI **scenario-irrelevant** hardware-specific information such as ACPI/PCI
and BDF information. The board configuration is organized as and BDF information. The board configuration is organized as
``*.c/*.h`` files located at:: ``*.c/*.h`` files located in the
``acrn-hypervisor/hypervisor/arch/x86/configs/$(BOARD)/`` folder.
acrn-hypervisor/hypervisor/arch/x86/configs/$(BOARD)/
VM configuration 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 configuration information, where parameters are passed to the device model
to launch post-launched User VMs. 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 in the
``acrn-hypervisor/devicemodel/samples/`` folder.
User VM launch script samples are located at::
acrn-hypervisor/devicemodel/samples/
ACRN configuration XMLs ACRN configuration XMLs
*********************** ***********************
The ACRN configuration includes three kinds of XMLs for acrn-config usage: The ACRN configuration includes three kinds of XML files for acrn-config
``board``, ``scenario``, and ``launch`` XML. All scenario-irrelevant usage: ``board``, ``scenario``, and ``launch`` XML. All
hardware-specific information for the board configuration is scenario-irrelevant hardware-specific information for the board
stored in the ``board`` XML. The XML is generated by ``misc/acrn-config/target/board_parser.py`` configuration is stored in the ``board`` XML. The XML is generated by
which runs on the target board. The scenario-relevant board and ``misc/acrn-config/target/board_parser.py``, which runs on the target
scenario-based VM board. The scenario-relevant board and scenario-based VM configurations
configurations are stored in the ``scenario`` XML. The launch script-based VM are stored in the ``scenario`` XML. The launch script-based VM
configuration is stored in the ``launch`` XML. These two XMLs can be customized configuration is stored in the ``launch`` XML. These two XMLs can be
by using the web inteface tool at ``misc/acrn-config/config-app/app.py``. End users can load customized by using the web interface tool at
their own configurations by importing customized XMLs or by saving the ``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. configurations by exporting XMLs.
Board XML format Board XML format
================ ================
The board XML located at: The board XMLs are located in the
acrn-hypervisor/misc/acrn-config/xmls/board-xmls ``acrn-hypervisor/misc/acrn-config/xmls/board-xmls/`` folder.
The board XML has an ``acrn-config`` root element and a ``board`` attribute: The board XML has an ``acrn-config`` root element and a ``board`` attribute:
.. code-block:: xml .. code-block:: xml
<acrn-config board=”BOARD”> <acrn-config board="BOARD">
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 Scenario XML format
=================== ===================
The scenario XML located at: The scenario XMLs are located in the
acrn-hypervisor/misc/acrn-config/xmls/config-xmls ``acrn-hypervisor/misc/acrn-config/xmls/config-xmls/`` folder. The
The scenario XML has an ``acrn-config`` root element as well as ``board`` and ``scenario`` attributes: scenario XML has an ``acrn-config`` root element as well as ``board``
and ``scenario`` attributes:
.. code-block:: xml .. code-block:: xml
<acrn-config board=”BOARD” scenario=”SCENARIO”> <acrn-config board="BOARD" scenario="SCENARIO">
Additional scenario XML elements: 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 Launch XML format
================= =================
The launch XML located at: The launch XMLs are located in the
acrn-hypervisor/misc/acrn-config/xmls/config-xmls ``acrn-hypervisor/misc/acrn-config/xmls/config-xmls/`` folder.
The launch XML has an ``acrn-config`` root element as well as The launch XML has an ``acrn-config`` root element as well as
``board``, ``scenario`` and ``uos_launcher`` attributes: ``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: 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:: .. 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 Configuration tool workflow
*************************** ***************************
@ -229,9 +275,7 @@ Board and VM configuration workflow
=================================== ===================================
Python offline tools are provided to configure Board and VM configurations. Python offline tools are provided to configure Board and VM configurations.
The tool source folder is located at:: The tool source folder is ``acrn-hypervisor/misc/acrn-config/``.
acrn-hypervisor/misc/acrn-config/
Here is the offline configuration tool workflow: Here is the offline configuration tool workflow:
@ -252,8 +296,15 @@ Here is the offline configuration tool workflow:
#. Customize your needs. #. Customize your needs.
a. Copy ``$(BOARD).xml`` to the host development machine. 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. #. Run the ``misc/acrn-config/config-app/app.py`` tool on the host
#. 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. 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. #. 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
@ -305,6 +356,7 @@ Use the ACRN configuration app
****************************** ******************************
The ACRN configuration app is a web user interface application that performs the following: The ACRN configuration app is a web user interface application that performs the following:
- reads board info - reads board info
- configures and validates scenario settings - configures and validates scenario settings
- automatically generates patches for board-related configurations and - automatically generates patches for board-related configurations and
@ -342,9 +394,12 @@ Instructions
$ python3 app.py $ python3 app.py
#. Open a browser and navigate to the website #. Open a browser and navigate to the website
`<http://127.0.0.1:5001/>`_ 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. `<http://127.0.0.1:5001/>`_ 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: The website is shown below:
@ -361,13 +416,14 @@ Instructions
#. Upload the board info you have generated from the ACRN config tool. #. 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 .. figure:: images/select_board_info.png
:align: center :align: center
#. Choose a scenario from the **Scenario Setting** menu which lists all the scenarios, #. 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 in the previous step. The scenario configuration xmls are located at
``acrn-hypervisor/misc/xmls/config-xmls/[board]/``. ``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 .. note:: All customized scenario xmls will be in user-defined groups which located in
``acrn-hypervisor/misc/xmls/config-xmls/[board]/user_defined/``. ``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 .. figure:: images/err_acrn_configuration.png
:align: center :align: center
@ -421,10 +479,11 @@ The **Launch Setting** is quite similar to the **Scenario Setting**:
#. Configure the items for the current launch 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. #. Click **Generate Launch Script** to save the current launch setting and then generate the launch script.
.. figure:: images/generate_launch_script.png .. figure:: images/generate_launch_script.png
:align: center :align: center