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

doc: update build-from-source instructions

Browse Source 
Users no longer need to explicitly generate configuration source code as
they are now generated at build time. This patch updates the relevant
instructions in the documentation.

v3:
 * RELEASE now defaults to n.
 * Cleanup the unnecessary target `all` in the `make` commands
 * Remove menuconfig related stuff.
 * Refine the introductory paragraph as only steps on Ubuntu is introduced
 * Also introduce the targets introduced by PR #5791

v2:
 * Add python3 lxml as a dependency
 * Explain how to use out-of-tree XML files

Tracked-On: #5644
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Co-authored-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This commit is contained in:
Junjie Mao 2021-02-22 16:44:14 +08:00 committed by fitchbe
parent 5df65eeb19
commit 9b4bf5e2a8
6 changed files with 108 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

212
doc/getting-started/building-from-source.rst
View File

@ -8,8 +8,8 @@ hypervisor is designed to be customized at build time per hardware
platform and per usage scenario, rather than one binary for all platform and per usage scenario, rather than one binary for all
scenarios. scenarios.
The hypervisor binary is generated based on Kconfig configuration The hypervisor binary is generated based on configuration settings in XML
settings. Instructions about these settings can be found in files. Instructions about customizing these settings can be found in
:ref:`getting-started-hypervisor-configuration`. :ref:`getting-started-hypervisor-configuration`.
One binary for all platforms and all usage scenarios is currently not One binary for all platforms and all usage scenarios is currently not
@ -48,19 +48,12 @@ these steps.
Install Build Tools and Dependencies Install Build Tools and Dependencies
************************************ ************************************
ACRN development is supported on popular Linux distributions, each with ACRN development is supported on popular Linux distributions, each with their
their own way to install development tools. This user guide covers the own way to install development tools. This user guide covers the steps to
different steps to configure and build ACRN natively on your configure and build ACRN natively on **Ubuntu 18.04 or newer**.
distribution.
.. note:: The following commands install the necessary tools for configuring and building
ACRN uses ``menuconfig``, a python3 text-based user interface (TUI) ACRN.
for configuring hypervisor options and using Python's ``kconfiglib``
library.
Install the necessary tools for the following systems:
* Ubuntu development system:
.. code-block:: none .. code-block:: none
@ -82,21 +75,16 @@ Install the necessary tools for the following systems:
libnuma-dev \ libnuma-dev \
liblz4-tool \ liblz4-tool \
flex \ flex \
bison bison \
xsltproc
$ sudo pip3 install kconfiglib $ sudo pip3 install lxml xmlschema
$ wget https://acpica.org/sites/acpica/files/acpica-unix-20191018.tar.gz $ wget https://acpica.org/sites/acpica/files/acpica-unix-20191018.tar.gz
$ tar zxvf acpica-unix-20191018.tar.gz $ tar zxvf acpica-unix-20191018.tar.gz
$ cd acpica-unix-20191018 $ cd acpica-unix-20191018
$ make clean && make iasl $ make clean && make iasl
$ sudo cp ./generate/unix/bin/iasl /usr/sbin/ $ sudo cp ./generate/unix/bin/iasl /usr/sbin/
.. note::
ACRN requires ``gcc`` version 7.3.* (or higher) and ``binutils`` version
2.27 (or higher). Check your development environment to ensure you have
appropriate versions of these packages by using the commands: ``gcc -v``
and ``ld -v``.
.. rst-class:: numbered-step .. rst-class:: numbered-step
Get the ACRN Hypervisor Source Code Get the ACRN Hypervisor Source Code
@ -107,7 +95,8 @@ repository contains four main components:
1. The ACRN hypervisor code, located in the ``hypervisor`` directory. 1. The ACRN hypervisor code, located in the ``hypervisor`` directory.
#. The ACRN device model code, located in the ``devicemodel`` directory. #. The ACRN device model code, located in the ``devicemodel`` directory.
#. The ACRN tools source code, located in the ``misc/tools`` 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.
Enter the following to get the acrn-hypervisor source code: Enter the following to get the acrn-hypervisor source code:
@ -149,126 +138,125 @@ HYBRID_RT:
pre-launched RTVM, one pre-launched Service VM, and one post-launched pre-launched RTVM, one pre-launched Service VM, and one post-launched
Standard VM. Standard VM.
Assuming that you are at the top level of the acrn-hypervisor directory, perform the following: XML configuration files for those 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:
.. note:: .. note::
The release version is built by default, ``RELEASE=0`` builds the debug version. 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
build exists.
* Build the ``INDUSTRY`` scenario on the ``nuc7i7dnb``: * Build the debug version of ``INDUSTRY`` scenario on the ``nuc7i7dnb``:
.. code-block:: none .. code-block:: none
$ make all BOARD=nuc7i7dnb SCENARIO=industry RELEASE=0 $ make BOARD=nuc7i7dnb SCENARIO=industry
* Build the ``HYBRID`` scenario on the ``whl-ipc-i5``: * Build the release version of ``HYBRID`` scenario on the ``whl-ipc-i5``:
.. code-block:: none .. code-block:: none
$ make all BOARD=whl-ipc-i5 SCENARIO=hybrid RELEASE=0 $ make BOARD=whl-ipc-i5 SCENARIO=hybrid RELEASE=y
* Build the ``HYBRID_RT`` scenario on the ``whl-ipc-i7``: * Build the release version of ``HYBRID_RT`` scenario on the ``whl-ipc-i7``
(hypervisor only):
.. code-block:: none .. code-block:: none
$ make all BOARD=whl-ipc-i7 SCENARIO=hybrid_rt RELEASE=0 $ make BOARD=whl-ipc-i7 SCENARIO=hybrid_rt RELEASE=y hypervisor
* Build the ``SDC`` scenario on the ``nuc6cayh``: * Build the release version of the device model and tools:
.. code-block:: none .. code-block:: none
$ make all BOARD_FILE=$PWD/misc/vm_configs/xmls/board-xmls/nuc6cayh.xml \ $ make RELEASE=y devicemodel tools
SCENARIO_FILE=$PWD/misc/vm_configs/xmls/config-xmls/nuc6cayh/sdc.xml
You can also build ACRN with your customized scenario:
See the :ref:`hardware` document for information about platform needs * Build with your own scenario configuration on the ``nuc6cayh``, assuming the
for each scenario. scenario is defined in ``/path/to/scenario.xml``:
.. code-block:: none
$ make BOARD=nuc6cayh SCENARIO=/path/to/scenario.xml
* Build with your own board and scenario configuration, assuming the board and
scenario XML files are ``/path/to/board.xml`` and ``/path/to/scenario.xml``:
.. code-block:: none
$ make BOARD=/path/to/board.xml SCENARIO=/path/to/scenario.xml
.. note::
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.
See the :ref:`hardware` document for information about platform needs for each
scenario. For more instructions to customize scenarios, see
:ref:`getting-started-hypervisor-configuration` and
:ref:`acrn_configuration_tool`.
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
``hvshowconfig`` target will help.
.. 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
.. _getting-started-hypervisor-configuration: .. _getting-started-hypervisor-configuration:
.. rst-class:: numbered-step .. rst-class:: numbered-step
Build the Hypervisor Configuration
**********************************
Modify the Hypervisor Configuration Modify the Hypervisor Configuration
=================================== ***********************************
The ACRN hypervisor leverages Kconfig to manage configurations; it is The ACRN hypervisor is built with scenario encoded in an XML file (referred to
powered by ``Kconfiglib``. A default configuration is generated based on the as the scenario XML hereinafter). The scenario XML of a build can be found at
board you have selected via the ``BOARD=`` command line parameter. You can ``<build>/hypervisor/.scenario.xml``, where ``<build>`` is the name of the build
make further changes to that default configuration to adjust to your specific directory. You can make further changes to this file to adjust to your specific
requirements. requirements. Another ``make`` will rebuild the hypervisor using the updated
scenario XML.
To generate hypervisor configurations, you must build the hypervisor The following commands show how to customize manually the scenario XML based on
individually. The following steps generate a default but complete the predefined ``INDUSTRY`` scenario for ``nuc7i7dnb`` and rebuild the
configuration, based on the platform selected, assuming that you are at the hypervisor.
top level of the acrn-hypervisor directory. The configuration file, named
``.config``, can be found under the target folder of your build.
.. code-block:: none .. code-block:: none
$ cd hypervisor $ make BOARD=nuc7i7dnb SCENARIO=industry hvdefconfig
$ make defconfig BOARD=nuc7i7dnb SCENARIO=industry $ vim build/hypervisor/.scenario.xml
(Modify the XML file per your needs)
The BOARD specified is used to select a ``defconfig`` under $ make
``misc/vm_configs/scenarios/``. The other command line-based options (e.g.
``RELEASE``) take no effect when generating a defconfig.
To modify the hypervisor configurations, you can either edit ``.config``
manually, or you can invoke a TUI-based menuconfig (powered by kconfiglib) by
executing ``make menuconfig``. As an example, the following commands
(assuming that you are at the top level of the acrn-hypervisor directory)
generate a default configuration file, allowing you to modify some
configurations and build the hypervisor using the updated ``.config``:
.. code-block:: none
# Modify the configurations per your needs
$ cd ../ # Enter top-level folder of acrn-hypervisor source
$ make menuconfig -C hypervisor
# modify your own "ACRN Scenario" and "Target board" that want to build
# in pop up menu
Note that ``menuconfig`` is python3 only.
Refer to the help on menuconfig for a detailed guide on the interface:
.. code-block:: none
$ pydoc3 menuconfig
.. rst-class:: numbered-step
Build the Hypervisor, Device Model, and Tools
*********************************************
Now you can build all these components at once as follows:
.. code-block:: none
$ make # Build hypervisor with the new .config
The build results are found in the ``build`` directory. You can specify
a different Output folder by setting the ``O`` ``make`` parameter,
for example: ``make O=build-nuc``.
.. code-block:: none
$ make all BOARD_FILE=$PWD/misc/vm_configs/xmls/board-xmls/nuc7i7dnb.xml \
SCENARIO_FILE=$PWD/misc/vm_configs/xmls/config-xmls/nuc7i7dnb/industry.xml TARGET_DIR=xxx
The build results are found in the ``build`` directory. You can specify
a different build folder by setting the ``O`` ``make`` parameter,
for example: ``make O=build-nuc``.
.. note:: .. note::
The ``BOARD`` and ``SCENARIO`` parameters are not needed because the A hypervisor build memorizes the board and scenario previously
information is retrieved from the corresponding ``BOARD_FILE`` and configured. Thus, there is no need to duplicate BOARD and SCENARIO in the
``SCENARIO_FILE`` XML configuration files. The ``TARGET_DIR`` parameter second ``make`` above.
specifies what directory is used to store configuration files imported
from XML files. If the ``TARGET_DIR`` is not specified, the original
configuration files of acrn-hypervisor would be overridden.
Follow the same instructions to boot and test the images you created from your build. 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
of the configuration entries. Refer to :ref:`acrn_config_tool_ui` for more
instructions.
Descriptions of each configuration entry in scenario XML files are also
available at :ref:`scenario-config-options`.

59
doc/tutorials/acrn_configuration_tool.rst
View File

@ -191,32 +191,6 @@ current scenario has:
Configuration Tool Workflow Configuration Tool Workflow
*************************** ***************************
Hypervisor Configuration Workflow
==================================
The hypervisor configuration is based on the ``Kconfig``
mechanism. Begin by creating a board-specific ``defconfig`` file to
set up the default ``Kconfig`` values for the specified board.
Next, configure the hypervisor build options using the ``make menuconfig``
graphical interface or ``make defconfig`` to generate
a ``.config`` file. The resulting ``.config`` file is
used by the ACRN build process to create a configured scenario- and
board-specific hypervisor image.
.. figure:: images/sample_of_defconfig.png
:align: center
defconfig file sample
.. figure:: images/GUI_of_menuconfig.png
:align: center
``menuconfig`` interface sample
Refer to :ref:`getting-started-hypervisor-configuration` for detailed
configuration steps.
.. _vm_config_workflow: .. _vm_config_workflow:
Board and VM Configuration Workflow Board and VM Configuration Workflow
@ -258,37 +232,8 @@ Here is the offline configuration tool workflow:
.. 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. the configuration tool UI.
#. Auto generate the code. #. Build with your XML files. Refer to :ref:`getting-started-building` to build
the ACRN hypervisor with your XML files on the host machine.
Python tools are used to generate configurations in patch format.
The patches are applied to your local ``acrn-hypervisor`` git tree
automatically.
a. Generate a patch for the board-related configuration::
cd misc/acrn-config/board_config
python3 board_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml
Note that this can also be done by clicking **Generate Board SRC** in the acrn-config UI.
#. Generate a patch for scenario-based VM configuration::
cd misc/acrn-config/scenario_config
python3 scenario_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml
Note that this can also be done by clicking **Generate Scenario SRC** in the acrn-config UI.
#. Generate the launch script for the specified
post-launched User VM::
cd misc/acrn-config/launch_config
python3 launch_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml --launch $(LAUNCH).xml --uosid xx
Note that this can also be done by clicking **Generate Launch Script** in the acrn-config UI.
#. Re-build the ACRN hypervisor. Refer to
:ref:`getting-started-building` to re-build the ACRN hypervisor on the host machine.
#. Deploy VMs and run ACRN hypervisor on the target board. #. Deploy VMs and run ACRN hypervisor on the target board.

5
doc/tutorials/enable_ivshmem.rst
View File

@ -178,7 +178,7 @@ Linux-based VMs (VM0 is a pre-launched VM and VM2 is a post-launched VM).
and shared memory size is 2M bytes: and shared memory size is 2M bytes:
- Edit XML configuration file for hybrid_rt scenario on whl-ipc-i5 board - Edit XML configuration file for hybrid_rt scenario on whl-ipc-i5 board
``acrn-hypervisor/misc/vm_configs/xmls/config-xmls/whl-ipc-i5/hybrid_rt.xml`` ``acrn-hypervisor/misc/config_tools/data/whl-ipc-i5/hybrid_rt.xml``
to enable ``ivshmem`` and configure the shared memory region using the format to enable ``ivshmem`` and configure the shared memory region using the format
``shm_name, shm_size, VM IDs`` (as described above in the ACRN dm boot parameters). ``shm_name, shm_size, VM IDs`` (as described above in the ACRN dm boot parameters).
The region name must start with ``hv:/`` for an hv-land shared region, and we'll allocate 2MB The region name must start with ``hv:/`` for an hv-land shared region, and we'll allocate 2MB
@ -194,8 +194,7 @@ Linux-based VMs (VM0 is a pre-launched VM and VM2 is a post-launched VM).
2. Build ACRN based on the XML configuration for hybrid_rt scenario on whl-ipc-i5 board:: 2. Build ACRN based on the XML configuration for hybrid_rt scenario on whl-ipc-i5 board::
make BOARD_FILE=acrn-hypervisor/misc/vm_configs/xmls/board-xmls/whl-ipc-i5.xml \ make BOARD=whl-ipc-i5 SCENARIO=hybrid_rt TARGET_DIR=xxx
SCENARIO_FILE=acrn-hypervisor/misc/vm_configs/xmls/config-xmls/whl-ipc-i5/hybrid_rt.xml TARGET_DIR=xxx
3. Add a new virtual PCI device for VM2 (post-launched VM): the device type is 3. Add a new virtual PCI device for VM2 (post-launched VM): the device type is
``ivshmem``, shared memory name is ``hv:/shm_region_0``, and shared memory ``ivshmem``, shared memory name is ``hv:/shm_region_0``, and shared memory

BIN
doc/tutorials/images/GUI_of_menuconfig.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 267 KiB

BIN
doc/tutorials/images/sample_of_defconfig.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 95 KiB

9
doc/tutorials/vuart_configuration.rst
View File

@ -267,7 +267,7 @@ and :ref:`How to Configure a Communication Port
<how-to-configure-a-communication-port>`. <how-to-configure-a-communication-port>`.
You can configure both Legacy vUART and PCI-vUART in You can configure both Legacy vUART and PCI-vUART in
``./misc/vm_configs/xmls/config-xmls/<board>/<scenario>.xml``. For ``./misc/config_tools/data/<board>/<scenario>.xml``. For
example, if VM0 has a legacy vUART0 and a PCI-vUART1, VM1 has no legacy example, if VM0 has a legacy vUART0 and a PCI-vUART1, VM1 has no legacy
vUART but has a PCI-vUART0 and a PCI-vUART1, VM0's PCI-vUART1 and VM1's vUART but has a PCI-vUART0 and a PCI-vUART1, VM0's PCI-vUART1 and VM1's
PCI-vUART1 are connected to each other. You should configure then like this: PCI-vUART1 are connected to each other. You should configure then like this:
@ -334,13 +334,12 @@ The ACRN vUART related XML fields:
Run the command to build ACRN with this XML configuration file:: Run the command to build ACRN with this XML configuration file::
make BOARD_FILE=$PWD/misc/acrn-config/xmls/board-xmls/<board>.xml \ make BOARD=<board> SCENARIO=<scenario>
SCENARIO_FILE=$PWD/misc/acrn-config/xmls/config-xmls/<board>/<scenario>.xml
The configuration tools will test your settings, and check :ref:`vUART The configuration tools will test your settings, and check :ref:`vUART
Rules <index-of-vuart>` for compilation issue. After compiling, you can find Rules <index-of-vuart>` for compilation issue. After compiling, you can find
``./misc/vm_configs/scenarios/<scenario>/<board>/pci_dev.c`` has been the generated sources under ``build/configs/scenarios/<scenario>/pci_dev.c``
changed by the configuration tools based on the XML settings, something like: which is based on the XML settings, something like:
.. code-block:: none .. code-block:: none