mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-09-08 04:09:11 +00:00
doc: create ACRN config tool/board inspector docs
- Create ACRN config tool doc based on info in existing "Intro to ACRN Configuration" doc, add clarifications - Create board inspector tool doc based on info in existing "Intro to ACRN Configuration" doc, add clarifications - Create launch config options doc based on info in existing "Intro to ACRN Configuration" doc, similar to existing scenario config options doc - Update refs that no longer exist - Create hypervisor makefile options doc, combining makefile info from "Intro to ACRN Configuration" doc and "Build ACRN from Source" doc - Clarify why you need config files, difference between scenario vs. launch VM settings - Updates are intended to reflect v2.6 code Signed-off-by: Amy Reyes <amy.reyes@intel.com>
This commit is contained in:
Amy Reyes
David Kinder
103
doc/reference/config-options-launch.rst
Normal file
103
doc/reference/config-options-launch.rst
Normal file
@@ -0,0 +1,103 @@
|
||||
.. _launch-config-options:
|
||||
|
||||
Launch Configuration Options
|
||||
##############################
|
||||
|
||||
As explained in :ref:`acrn_configuration_tool`, launch configuration files
|
||||
define post-launched User VM settings. This document describes these option settings.
|
||||
|
||||
``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``, ``ALIOS``,
|
||||
``PREEMPT-RT LINUX``, ``GENERIC LINUX``, ``WINDOWS``, ``YOCTO``, ``UBUNTU``,
|
||||
``ZEPHYR`` or ``VXWORKS``.
|
||||
|
||||
``rtos_type``:
|
||||
Specify the User VM Real-time capability: Soft RT, Hard RT, or none of them.
|
||||
|
||||
``mem_size``:
|
||||
Specify the User VM memory size in megabytes.
|
||||
|
||||
``gvt_args``:
|
||||
GVT arguments for the VM. Set it to ``gvtd`` for GVT-d, otherwise it's
|
||||
for GVT-g arguments. The GVT-g input format:
|
||||
``low_gm_size high_gm_size fence_sz``,
|
||||
The recommendation is ``64 448 8``. Leave it blank to disable the GVT.
|
||||
|
||||
``vbootloader``:
|
||||
Virtual bootloader type; currently only supports OVMF.
|
||||
|
||||
``vuart0``:
|
||||
Specify whether the device model emulates the vUART0(vCOM1); refer to
|
||||
:ref:`vuart_config` for details. If set to ``Enable``, the vUART0 is
|
||||
emulated by the device model; if set to ``Disable``, the vUART0 is
|
||||
emulated by the hypervisor if it is configured in the scenario XML.
|
||||
|
||||
``poweroff_channel``:
|
||||
Specify whether the User VM power off channel is through the IOC,
|
||||
power button, or vUART.
|
||||
|
||||
``allow_trigger_s5``:
|
||||
Allow VM to trigger s5 shutdown flow, this flag works with
|
||||
``poweroff_channel``
|
||||
``vuart1(pty)`` and ``vuart1(tty)`` only.
|
||||
|
||||
``enable_ptm``:
|
||||
Enable the Precision Timing Measurement (PTM) feature.
|
||||
|
||||
``usb_xhci``:
|
||||
USB xHCI mediator configuration. Input format:
|
||||
``bus#-port#[:bus#-port#: ...]``, e.g.: ``1-2:2-4``.
|
||||
Refer to :ref:`usb_virtualization` for details.
|
||||
|
||||
``shm_regions``:
|
||||
List of shared memory regions for inter-VM communication.
|
||||
|
||||
``shm_region`` (a child node of ``shm_regions``):
|
||||
configure the shared memory regions for current VM, input format:
|
||||
``hv:/<;shm name>; (or dm:/<shm_name>;), <;shm size in MB>;``. Refer
|
||||
to :ref:`ivshmem-hld` for details.
|
||||
|
||||
``console_vuart``:
|
||||
Enable a PCI-based console vUART. Refer to :ref:`vuart_config` for details.
|
||||
|
||||
``communication_vuarts``:
|
||||
List of PCI-based communication vUARTs. Refer to :ref:`vuart_config` for
|
||||
details.
|
||||
|
||||
``communication_vuart`` (a child node of ``communication_vuarts``):
|
||||
Enable a PCI-based communication vUART with its ID. Refer to
|
||||
:ref:`vuart_config` for details.
|
||||
|
||||
``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``, ``sata``, and ``nvme``.
|
||||
|
||||
``network`` (a child node of ``virtio_devices``):
|
||||
The virtio network device setting.
|
||||
Input format: ``tap_name,[vhost],[mac=XX:XX:XX:XX:XX:XX]``.
|
||||
|
||||
``block`` (a child node of ``virtio_devices``):
|
||||
The virtio block device setting.
|
||||
Input format: ``[blk partition:][img path]`` e.g.: ``/dev/sda3:./a/b.img``.
|
||||
|
||||
``console`` (a child node of ``virtio_devices``):
|
||||
The virtio console device setting.
|
||||
Input format:
|
||||
``[@]stdio|tty|pty|sock:portname[=portpath][,[@]stdio|tty|pty:portname[=portpath]]``.
|
||||
|
||||
``cpu_affinity``:
|
||||
List of pCPU that this VM's vCPUs are pinned to.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``configurable`` and ``readonly`` attributes are used to mark
|
||||
whether the item is configurable for users. When ``configurable="n"``
|
||||
and ``readonly="y"``, the item is not configurable from the web
|
||||
interface. When ``configurable="n"``, the item does not appear on the
|
||||
interface.
|
||||
@@ -108,7 +108,7 @@ For general instructions setting up ACRN on supported hardware platforms, visit
|
||||
|
||||
If an XML file is not provided by project ACRN for your board, we recommend you
|
||||
use the board inspector tool to generate an XML file specifically for your board.
|
||||
Refer to the :ref:`acrn_configuration_tool` for more details on using the board inspector
|
||||
Refer to :ref:`board_inspector_tool` for more details on using the board inspector
|
||||
tool.
|
||||
|
||||
|
||||
|
||||
199
doc/reference/hv-make-options.rst
Normal file
199
doc/reference/hv-make-options.rst
Normal file
@@ -0,0 +1,199 @@
|
||||
.. _hypervisor-make-options:
|
||||
|
||||
Hypervisor Makefile Options
|
||||
###########################
|
||||
|
||||
The ACRN hypervisor source code provides a makefile to build the ACRN
|
||||
hypervisor binary and associated components.
|
||||
|
||||
Assuming that you are at the top level of the ``acrn-hypervisor`` directory,
|
||||
you can run the ``make`` command to start the build. See :ref:`acrn_configuration_tool` for information about required input files.
|
||||
|
||||
Build Options
|
||||
*************
|
||||
|
||||
The following table shows ACRN-specific command-line options:
|
||||
|
||||
.. list-table::
|
||||
:widths: 33 77
|
||||
:header-rows: 1
|
||||
|
||||
* - Option
|
||||
- Description
|
||||
|
||||
* - ``BOARD``
|
||||
- Required. Path to the board configuration file.
|
||||
|
||||
* - ``SCENARIO``
|
||||
- Required. Path to the scenario configuration file.
|
||||
|
||||
* - ``RELEASE``
|
||||
- Optional. Build a release version or a debug version. Valid values
|
||||
are ``y`` for release version or ``n`` for debug version. (Default
|
||||
is ``n``.)
|
||||
|
||||
* - ``hypervisor``
|
||||
- Optional. Build the hypervisor only.
|
||||
|
||||
* - ``devicemodel``
|
||||
- Optional. Build the Device Model only.
|
||||
|
||||
* - ``tools``
|
||||
- Optional. Build the tools only.
|
||||
|
||||
* - ``O``
|
||||
- Optional. Path to the directory where the built files will be stored.
|
||||
(Default is the ``build`` directory.)
|
||||
|
||||
Example of a command to build the debug version:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/industry.xml
|
||||
|
||||
Example of a command to build the release version:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/industry.xml RELEASE=y
|
||||
|
||||
Example of a command to build the release version (hypervisor only):
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/industry.xml RELEASE=y hypervisor
|
||||
|
||||
Example of a command to build the release version of the Device Model and tools:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
make RELEASE=y devicemodel tools
|
||||
|
||||
Example of a command to put the built files in the specified directory
|
||||
(``build-nuc``):
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
make O=build-nuc BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/industry.xml
|
||||
|
||||
ACRN uses XML files to summarize board characteristics and scenario settings.
|
||||
The ``BOARD`` and ``SCENARIO`` variables accept board/scenario names as well
|
||||
as paths to XML files. When board/scenario names are given, the build system
|
||||
searches for XML files with the same names under ``misc/config_tools/data/``.
|
||||
When paths (absolute or relative) to the XML files are given, the build system
|
||||
uses the files pointed at. If relative paths are used, they are considered
|
||||
relative to the current working directory.
|
||||
|
||||
.. _acrn_makefile_targets:
|
||||
|
||||
Makefile Targets for Configuration
|
||||
***********************************
|
||||
|
||||
ACRN source also includes the following makefile targets to aid customization.
|
||||
|
||||
.. list-table::
|
||||
:widths: 33 77
|
||||
:header-rows: 1
|
||||
|
||||
* - Target
|
||||
- Description
|
||||
|
||||
* - ``hvdefconfig``
|
||||
- Generate configuration files (a bunch of C source files) in the build
|
||||
directory without building the hypervisor. This target can be used when
|
||||
you want to customize the configurations based on a predefined scenario.
|
||||
|
||||
* - ``hvshowconfig``
|
||||
- Print the target ``BOARD``, ``SCENARIO`` and build type (debug or
|
||||
release) of a build.
|
||||
|
||||
* - ``hvdiffconfig``
|
||||
- After modifying the generated configuration files, you can use this
|
||||
target to generate a patch that shows the differences made.
|
||||
|
||||
* - ``hvapplydiffconfig PATCH=/path/to/patch``
|
||||
- Register a patch to be applied on the generated configuration files
|
||||
every time they are regenerated. The ``PATCH`` variable specifies the
|
||||
path (absolute or relative to current working directory) of the patch.
|
||||
Multiple patches can be registered by invoking this target multiple
|
||||
times.
|
||||
|
||||
Example of ``hvshowconfig`` to query the board, scenario, and build
|
||||
type of an existing build:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make BOARD=tgl-rvp SCENARIO=hybrid_rt hypervisor
|
||||
...
|
||||
$ make hvshowconfig
|
||||
Build directory: /path/to/acrn-hypervisor/build/hypervisor
|
||||
This build directory is configured with the settings below.
|
||||
- BOARD = tgl-rvp
|
||||
- SCENARIO = hybrid_rt
|
||||
- RELEASE = n
|
||||
|
||||
Example of ``hvdefconfig`` to generate the configuration files in the
|
||||
build directory, followed by an example of editing one of the configuration
|
||||
files manually (``scenario.xml``) and then building the hypervisor:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
make BOARD=nuc7i7dnb SCENARIO=industry hvdefconfig
|
||||
vim build/hypervisor/.scenario.xml
|
||||
#(Modify the XML file per your needs)
|
||||
make
|
||||
|
||||
A hypervisor build remembers the board and scenario previously configured.
|
||||
Thus, there is no need to duplicate ``BOARD`` and ``SCENARIO`` in the second
|
||||
``make`` above.
|
||||
|
||||
While the scenario configuration files can be changed manually, we recommend
|
||||
you use the :ref:`ACRN configurator tool <acrn_configurator_tool>`, which
|
||||
provides valid options and descriptions of the configuration entries.
|
||||
|
||||
The targets ``hvdiffconfig`` and ``hvapplydiffconfig`` are provided for users
|
||||
who already have offline patches to the generated configuration files. Prior to
|
||||
v2.4, the generated configuration files are also in the repository. Some users
|
||||
may already have chosen to modify these files directly to customize the
|
||||
configurations.
|
||||
|
||||
.. note::
|
||||
|
||||
We highly recommend new users save and maintain customized configurations in
|
||||
XML, not in patches to generated configuration files.
|
||||
|
||||
Example of how to use ``hvdiffconfig`` to generate a patch and save
|
||||
it to ``config.patch``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
acrn-hypervisor$ make BOARD=ehl-crb-b SCENARIO=hybrid_rt hvdefconfig
|
||||
...
|
||||
acrn-hypervisor$ vim build/hypervisor/configs/scenarios/hybrid_rt/pci_dev.c
|
||||
(edit the file manually)
|
||||
acrn-hypervisor$ make hvdiffconfig
|
||||
...
|
||||
Diff on generated configuration files is available at /path/to/acrn-hypervisor/build/hypervisor/config.patch.
|
||||
To make a patch effective, use 'applydiffconfig PATCH=/path/to/patch' to register it to a build.
|
||||
...
|
||||
acrn-hypervisor$ cp build/hypervisor/config.patch config.patch
|
||||
|
||||
Example of how to use ``hvapplydiffconfig`` to apply
|
||||
``config.patch`` to a new build:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
acrn-hypervisor$ make clean
|
||||
acrn-hypervisor$ make BOARD=ehl-crb-b SCENARIO=hybrid_rt hvdefconfig
|
||||
...
|
||||
acrn-hypervisor$ make hvapplydiffconfig PATCH=config.patch
|
||||
...
|
||||
/path/to/acrn-hypervisor/config.patch is registered for build directory /path/to/acrn-hypervisor/build/hypervisor.
|
||||
Registered patches will be applied the next time 'make' is invoked.
|
||||
To unregister a patch, remove it from /path/to/acrn-hypervisor/build/hypervisor/configs/.diffconfig.
|
||||
...
|
||||
acrn-hypervisor$ make hypervisor
|
||||
...
|
||||
Applying patch /path/to/acrn-hypervisor/config.patch:
|
||||
patching file scenarios/hybrid_rt/pci_dev.c
|
||||
...
|
||||
Reference in New Issue
Block a user