From 6e4e619e17560ea171593bf4d1d39134a9a650b5 Mon Sep 17 00:00:00 2001 From: Amy Reyes Date: Tue, 28 Sep 2021 07:05:21 -0700 Subject: [PATCH] Address review feedback for launch config options, makefile options, intro Signed-off-by: Amy Reyes --- doc/reference/config-options-launch.rst | 12 ++--- doc/reference/hv-make-options.rst | 57 ++++++++++++++++++----- doc/tutorials/acrn_configuration_tool.rst | 5 +- 3 files changed, 54 insertions(+), 20 deletions(-) diff --git a/doc/reference/config-options-launch.rst b/doc/reference/config-options-launch.rst index 55c8fd764..52cc43529 100644 --- a/doc/reference/config-options-launch.rst +++ b/doc/reference/config-options-launch.rst @@ -28,7 +28,7 @@ define post-launched User VM settings. This document describes these option sett Virtual bootloader type; currently only supports OVMF. ``vuart0``: - Specify whether the device model emulates the vUART0(vCOM1); refer to + 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. @@ -54,9 +54,9 @@ define post-launched User VM settings. This document describes these option sett 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 size in MB>;``. Refer - to :ref:`ivshmem-hld` for details. + Configure the shared memory regions for the current VM, input format: + ``[hv|dm]:/,``. Refer to :ref:`ivshmem-hld` + for details. ``console_vuart``: Enable a PCI-based console vUART. Refer to :ref:`vuart_config` for details. @@ -70,14 +70,14 @@ define post-launched User VM settings. This document describes these option sett :ref:`vuart_config` for details. ``passthrough_devices``: - Select the passthrough device from the lspci list. Currently we support: + Select the passthrough device from the PCI device 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]``. + Input format: ``[tap_name|macvtap_name],[vhost],[mac=XX:XX:XX:XX:XX:XX]``. ``block`` (a child node of ``virtio_devices``): The virtio block device setting. diff --git a/doc/reference/hv-make-options.rst b/doc/reference/hv-make-options.rst index af1d42046..062d5c98b 100644 --- a/doc/reference/hv-make-options.rst +++ b/doc/reference/hv-make-options.rst @@ -3,15 +3,15 @@ Hypervisor Makefile Options ########################### -The ACRN hypervisor source code provides a makefile to build the ACRN +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 -************* +Build Options and Targets +************************** The following table shows ACRN-specific command-line options: @@ -33,19 +33,45 @@ The following table shows ACRN-specific command-line options: 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. + * - ``ASL_COMPILER`` + - Optional. Use an ``iasl`` compiler that is not in the default path + (``/usr/sbin``). * - ``O`` - Optional. Path to the directory where the built files will be stored. (Default is the ``build`` directory.) +The following table shows ACRN-specific targets: + +.. list-table:: + :widths: 33 77 + :header-rows: 1 + + * - Makefile Target + - Description + + * - ``hypervisor`` + - Optional. Build the hypervisor. + + * - ``devicemodel`` + - Optional. Build the Device Model. The ``tools`` will also be built as + a dependency. + + * - ``tools`` + - Optional. Build the tools. + + * - ``doc`` + - Optional. Build the project's HTML documentation (using Sphinx), output + to the ``build/doc`` folder. + + * - ``life_mngr`` + - Optional. Build the Lifecycle Manager daemon that runs in the User VM + to manage power state transitions (S5). + + * - ``targz-pkg`` + - Optional. Create a compressed tarball (``acrn-$(FULL_VERSION).tar.gz``) + in the build folder (default: ``build``) with all the build artifacts. + Example of a command to build the debug version: .. code-block:: none @@ -77,6 +103,12 @@ Example of a command to put the built files in the specified directory make O=build-nuc BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/industry.xml +Example of a command that specifies ``iasl`` compiler: + +.. code-block:: none + + make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/industry.xml ASL_COMPILER=/usr/local/bin/iasl + 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 @@ -175,7 +207,8 @@ it to ``config.patch``: 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. + To make a patch effective, use 'hvapplydiffconfig PATCH=/path/to/patch' to + register it to a build. ... acrn-hypervisor$ cp build/hypervisor/config.patch config.patch diff --git a/doc/tutorials/acrn_configuration_tool.rst b/doc/tutorials/acrn_configuration_tool.rst index ae6a2dc77..306c5c3a1 100644 --- a/doc/tutorials/acrn_configuration_tool.rst +++ b/doc/tutorials/acrn_configuration_tool.rst @@ -143,8 +143,9 @@ configuration files. Although we recommend using the ACRN configuration toolset to create these files, this reference may be useful for advanced usage and troubleshooting. -ACRN source code offers predefined XMLs in the ``misc/config_tools/data/`` -directory of the ``acrn-hypervisor`` repo. +ACRN source code offers predefined XMLs, and the generic templates used for +new boards and scenarios, in the ``misc/config_tools/data/`` directory of +the ``acrn-hypervisor`` repo. Board XML Format ================