doc: review edits for acrn_configuration_tool
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder
David Kinder
parent
0d86951e46
commit
38abceb761
|
|
@ -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
|
||||
|
||||
<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
|
||||
===================
|
||||
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
|
||||
|
||||
<acrn-config board=”BOARD” scenario=”SCENARIO”>
|
||||
<acrn-config board="BOARD" scenario="SCENARIO">
|
||||
|
||||
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
|
||||
`<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:
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue