diff --git a/doc/getting-started/building-from-source.rst b/doc/getting-started/building-from-source.rst index b9a242b87..30336e50f 100644 --- a/doc/getting-started/building-from-source.rst +++ b/doc/getting-started/building-from-source.rst @@ -12,9 +12,9 @@ The hypervisor binary is generated based on configuration settings in XML files. Instructions about customizing these settings can be found in :ref:`getting-started-hypervisor-configuration`. -One binary for all platforms and all usage scenarios is currently not -supported, primarily because dynamic configuration parsing is restricted in -the ACRN hypervisor for the following reasons: +One binary for all platforms and all usage scenarios is not +supported. Dynamic configuration parsing is not used in +the ACRN hypervisor for these reasons: - **Maintain functional safety requirements.** Implementing dynamic parsing introduces dynamic objects, which violate functional safety requirements. @@ -90,15 +90,15 @@ ACRN. Get the ACRN Hypervisor Source Code *********************************** -The `acrn-hypervisor `_ +The `ACRN hypervisor `_ repository contains four main components: -1. The ACRN hypervisor code, located in the ``hypervisor`` directory. -#. The ACRN device model code, located in the ``devicemodel`` directory. -#. The ACRN debug tools source code, located in the ``misc/debug_tools`` directory. -#. The ACRN online services source code, located in the ``misc/services`` directory. +1. The ACRN hypervisor code is in the ``hypervisor`` directory. +#. The ACRN device model code is in the ``devicemodel`` directory. +#. The ACRN debug tools source code is in the ``misc/debug_tools`` directory. +#. The ACRN online services source code is in the ``misc/services`` directory. -Enter the following to get the acrn-hypervisor source code: +Enter the following to get the ACRN hypervisor source code: .. code-block:: none @@ -123,10 +123,10 @@ LOGICAL_PARTITION: This scenario defines two pre-launched VMs. INDUSTRY: - This is a typical scenario for industrial usage with up to eight VMs: + This scenario is an example for industrial usage with up to eight VMs: one pre-launched Service VM, five post-launched Standard VMs (for Human interaction etc.), one post-launched RT VMs (for real-time control), - and one Kata container VM. + and one Kata Container VM. HYBRID: This scenario defines a hybrid use case with three VMs: one @@ -138,15 +138,15 @@ HYBRID_RT: pre-launched RTVM, one pre-launched Service VM, and one post-launched Standard VM. -XML configuration files for those scenarios on supported boards are available +XML configuration files for these scenarios on supported boards are available under the ``misc/config_tools/data`` directory. Assuming that you are at the top level of the ``acrn-hypervisor`` directory, perform -the following to build the hypervisor, device model and tools: +the following to build the hypervisor, device model, and tools: .. note:: - The debug version is built by default. To build a release version, a user - must builds with ``RELEASE=y`` explicitly, regardless of whether a previous + The debug version is built by default. To build a release version, + build with ``RELEASE=y`` explicitly, regardless of whether a previous build exists. * Build the debug version of ``INDUSTRY`` scenario on the ``nuc7i7dnb``: @@ -209,7 +209,7 @@ The build results are found in the ``build`` directory. You can specify a different build directory by setting the ``O`` ``make`` parameter, for example: ``make O=build-nuc``. -To query the board, scenario and build type of an existing build, the +To query the board, scenario, and build type of an existing build, the ``hvshowconfig`` target will help. .. code-block:: none @@ -239,7 +239,8 @@ scenario XML. The following commands show how to customize manually the scenario XML based on the predefined ``INDUSTRY`` scenario for ``nuc7i7dnb`` and rebuild the -hypervisor. +hypervisor. The ``hvdefconfig`` target generates the configuration files without +building the hypervisor, allowing users to tweak the configurations. .. code-block:: none @@ -249,12 +250,12 @@ hypervisor. $ make .. note:: - A hypervisor build memorizes the board and scenario previously + 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 XML files can be changed manually, we recommend to use the -ACRN web-based configuration app which provides valid options and descriptions +While the scenario XML files can be changed manually, we recommend you use the +ACRN web-based configuration app that provides valid options and descriptions of the configuration entries. Refer to :ref:`acrn_config_tool_ui` for more instructions. diff --git a/doc/tutorials/acrn_configuration_tool.rst b/doc/tutorials/acrn_configuration_tool.rst index 24933e4be..f9978b3d3 100644 --- a/doc/tutorials/acrn_configuration_tool.rst +++ b/doc/tutorials/acrn_configuration_tool.rst @@ -9,13 +9,13 @@ well as configure hypervisor capabilities and provision VMs. ACRN configuration consists of the following key components. - - Configuration data which are saved as XML files. + - Configuration data saved as XML files. - A configuration toolset that helps users to generate and edit configuration data. The toolset includes: - - A **board inspector** which collects board-specific information on target + - A **board inspector** that collects board-specific information on target machines. - - A **configuration editor** which edits configuration data via web-based UI. + - A **configuration editor** that lets you edit configuration data via a web-based UI. The following sections introduce the concepts and tools of ACRN configuration from the aspects below. @@ -25,7 +25,7 @@ from the aspects below. - :ref:`acrn_config_workflow` overviews the steps to customize ACRN configuration using the configuration toolset. - :ref:`acrn_config_data` explains the location and format of configuration - data which are saved as XML files. + data saved as XML files. - :ref:`acrn_config_tool_ui` gives detailed instructions on using the configuration editor. @@ -34,7 +34,7 @@ from the aspects below. Types of Configurations *********************** -ACRN includes three types of configurations: board, scenario and launch. The +ACRN includes three types of configurations: board, scenario, and launch. The following sections briefly describe the objectives and main contents of each type. @@ -43,7 +43,7 @@ Board Configuration The board configuration stores hardware-specific information extracted on the target platform. It describes the capacity of hardware resources (such as -processors and memory), platform power states, available devices and BIOS +processors and memory), platform power states, available devices, and BIOS versions. This information is used by ACRN configuration tool to check feature availability and allocate resources among VMs, as well as by ACRN hypervisor to initialize and manage the platform at runtime. @@ -61,7 +61,7 @@ following in scenario configuration. - Hypervisor capabilities - Availability and settings of hypervisor features, such as debugging - facilities, scheduling algorithm, ivshmem and security features. + facilities, scheduling algorithm, ivshmem, and security features. - Hardware management capacity of the hypervisor, such as maximum PCI devices and maximum interrupt lines supported. - Memory consumption of the hypervisor, such as the entry point and stack @@ -72,7 +72,7 @@ following in scenario configuration. - VM attributes, such as VM names. - Maximum number of VMs supported. - Resources allocated to each VM, such as number of vCPUs, amount of guest - memory and pass-through devices. + memory, and pass-through devices. - Guest OS settings, such as boot protocol and guest kernel parameters. - Settings of virtual devices, such as virtual UARTs. @@ -91,9 +91,9 @@ Launch Configuration The launch configuration defines the attributes and resources of a post-launched VM. The main contents are similar to the VM attributes and -resources in scenario configuration. It is used to generate shell scripts that +resources in scenario configuration. The launch configuration is used to generate shell scripts that invoke ``acrn-dm`` to create post-launched VMs. Unlike board and scenario -configurations which are used at build time or by ACRN hypervisor, launch +configurations used at build time or by ACRN hypervisor, launch configuration are used dynamically in the Service VM. .. _acrn_config_workflow: @@ -130,12 +130,12 @@ toolset. #. Run the ACRN configuration editor (available at ``misc/config_tools/config_app/app.py``) 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 + and input the desired scenario settings. The tool will do validation checks on the input based on the ``$(BOARD).xml``. The customized settings can be exported to your own ``$(SCENARIO).xml``. If you have a customized scenario XML file, you can also import it to the editor for modification. #. In ACRN configuration editor, input the launch script parameters for the - post-launched User VM under **Launch Setting**. The editor will sanity check + post-launched User VM under **Launch Setting**. The editor will validate the input based on both the ``$(BOARD).xml`` and ``$(SCENARIO).xml`` and then export settings to your ``$(LAUNCH).xml``. @@ -152,6 +152,86 @@ toolset. Configuration Workflow +Makefile Targets for Configuration +================================== + +In addition to the ``BOARD`` and ``SCENARIO`` variables, ACRN source also +includes the following makefile targets to aid customization. + +.. list-table:: + :widths: 20 50 + :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. + +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. + +Here is an example how to use the ``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 + +The example below shows 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 + ... + .. _acrn_config_data: ACRN Configuration Data @@ -177,7 +257,7 @@ The board XML has an ``acrn-config`` root element and a ``board`` attribute: -As an input to the configuration editor and the build system, board XMLs are not +Board XML files are input to the configuration editor and the build system, and are not intended for end users to modify. Scenario XML Format @@ -287,7 +367,7 @@ Use the ACRN Configuration Editor The ACRN configuration editor provides a web-based user interface for the following: - reads board info -- configures and validates scenario and launch configurationss +- configures and validates scenario and launch configurations - generates launch scripts for the specified post-launched User VMs. - dynamically creates a new scenario configuration and adds or deletes VM settings in it @@ -300,7 +380,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 the ACRN hypervisor repo:: .. code-block:: none @@ -409,7 +489,7 @@ Instructions pop-up model. .. note:: - All customized scenario XMLs will be in user-defined groups, which are + All customized scenario XMLs will be in user-defined groups located in ``misc/config_tools/data/[board]/user_defined/``. Before saving the scenario XML, the configuration editor validates the @@ -441,7 +521,7 @@ The **Launch Setting** is quite similar to the **Scenario Setting**: #. Configure the items for the current launch configuration. -#. To dynamically add or remove User VM (UOS) launch scripts: +#. Add or remove User VM (UOS) launch scripts: - Add a UOS launch script by clicking **Configure an UOS below** for the current launch configuration. diff --git a/doc/tutorials/vuart_configuration.rst b/doc/tutorials/vuart_configuration.rst index 9efb08c9f..0cd0c31fe 100644 --- a/doc/tutorials/vuart_configuration.rst +++ b/doc/tutorials/vuart_configuration.rst @@ -10,9 +10,9 @@ The virtual universal asynchronous receiver/transmitter (vUART) supports two functions: one is the console, the other is communication. vUART only works on a single function. -Currently, only two vUART configurations are added to the predefined scenarios, +Only two vUART configurations are added to the predefined scenarios, but you can customize the scenarios to enable more using the :ref:`ACRN -configuration toolset ` +configuration toolset `. Console Enable List =================== @@ -69,7 +69,7 @@ The port_base and IRQ should differ from the ``vuart[0]`` in the same VM. ``t_vuart.vm_id`` is the target VM's vm_id, start from 0. (0 means VM0) -``t_vuart.vuart_id`` is the target vuart index in the target VM. Start +``t_vuart.vuart_id`` is the target vUART index in the target VM. Start from ``1``. (``1`` means ``vuart[1]``) Example: @@ -200,7 +200,7 @@ started, as shown in the diagram below: .. note:: For operating systems such as VxWorks and Windows that depend on the ACPI table to probe the UART driver, adding the vUART configuration in - the hypervisor is not sufficient. Currently, we recommend that you use + the hypervisor is not sufficient. We recommend that you use the configuration in the figure 3 data flow. This may be refined in the future. @@ -229,7 +229,7 @@ to 8 vUART for each VM, from ``vuart_idx=0`` to ``vuart_idx=7``. Suppose we use vUART0 for a port with ``vuart_idx=0``, vUART1 for ``vuart_idx=1``, and so on. -Please pay attention to these points: +Pay attention to these points: * vUART0 is the console port, vUART1-vUART7 are inter-VM communication ports. * Each communication port must set the connection to another communication vUART port of another VM. @@ -304,7 +304,7 @@ The ACRN vUART related XML fields: legacy ``vuart[0]`` configuration, ``id=1`` is for ``vuart[1]``. - ``type`` in ````, type is always ``VUART_LEGACY_PIO`` for legacy vUART. - - ``base`` in ````, if use the legacy vUART port, set + - ``base`` in ````, if using the legacy vUART port, set COM1_BASE for ``vuart[0]``, set ``COM2_BASE`` for ``vuart[1]``. ``INVALID_COM_BASE`` means do not use the legacy vUART port. - ``irq`` in ````, if you use the legacy vUART port, set @@ -324,8 +324,8 @@ Run the command to build ACRN with this XML configuration file:: The configuration tools will test your settings, and check :ref:`vUART Rules ` for compilation issue. After compiling, you can find the generated sources under -``build/hypervisor/configs/scenarios//pci_dev.c`` -which is based on the XML settings, something like: +``build/hypervisor/configs/scenarios//pci_dev.c``, +based on the XML settings, something like: .. code-block:: none @@ -342,7 +342,7 @@ which is based on the XML settings, something like: }, } -This struct shows a PCI-vUART with ``vuart_idx=1``, ``BDF 00:05.0``, its +This struct shows a PCI-vUART with ``vuart_idx=1``, ``BDF 00:05.0``, it's a PCI-vUART1 of VM0, and it is connected to VM1's vUART1 port. When VM0 wants to communicate with VM1, it can use ``/dev/ttyS*``, the character device file of @@ -388,6 +388,6 @@ Kernel Cmdline for PCI-vUART Console When an ACRN VM does not have a legacy ``vuart[0]`` but has a PCI-vUART0, you can use PCI-vUART0 for VM serial input/output. Check -which tty has the BDF of PCI-vUART0; usually it is not ``/dev/ttyS0``. +which TTY has the BDF of PCI-vUART0; usually it is not ``/dev/ttyS0``. For example, if ``/dev/ttyS4`` is PCI-vUART0, you must set ``console=/dev/ttyS4`` in the kernel cmdline.