github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-09-06 11:20:32 +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
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
scenarios.
The hypervisor binary is generated based on Kconfig configuration
settings. Instructions about these settings can be found in
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
@@ -48,19 +48,12 @@ these steps.
Install Build Tools and Dependencies
************************************
ACRN development is supported on popular Linux distributions, each with
their own way to install development tools. This user guide covers the
different steps to configure and build ACRN natively on your
distribution.
ACRN development is supported on popular Linux distributions, each with their
own way to install development tools. This user guide covers the steps to
configure and build ACRN natively on **Ubuntu 18.04 or newer**.
.. note::
ACRN uses ``menuconfig``, a python3 text-based user interface (TUI)
for configuring hypervisor options and using Python's ``kconfiglib``
library.
Install the necessary tools for the following systems:
* Ubuntu development system:
The following commands install the necessary tools for configuring and building
ACRN.
.. code-block:: none
@@ -82,21 +75,16 @@ Install the necessary tools for the following systems:
libnuma-dev \
liblz4-tool \
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
$ tar zxvf acpica-unix-20191018.tar.gz
$ cd acpica-unix-20191018
$ make clean && make iasl
$ 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
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.
#. 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:
@@ -149,126 +138,125 @@ HYBRID_RT:
pre-launched RTVM, one pre-launched Service VM, and one post-launched
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::
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
$ 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
$ 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
$ 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
$ make all BOARD_FILE=$PWD/misc/vm_configs/xmls/board-xmls/nuc6cayh.xml \
SCENARIO_FILE=$PWD/misc/vm_configs/xmls/config-xmls/nuc6cayh/sdc.xml
$ make RELEASE=y devicemodel tools
You can also build ACRN with your customized scenario:
See the :ref:`hardware` document for information about platform needs
for each scenario.
* Build with your own scenario configuration on the ``nuc6cayh``, assuming the
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:
.. rst-class:: numbered-step
Build the Hypervisor Configuration
**********************************
Modify the Hypervisor Configuration
===================================
***********************************
The ACRN hypervisor leverages Kconfig to manage configurations; it is
powered by ``Kconfiglib``. A default configuration is generated based on the
board you have selected via the ``BOARD=`` command line parameter. You can
make further changes to that default configuration to adjust to your specific
requirements.
The ACRN hypervisor is built with scenario encoded in an XML file (referred to
as the scenario XML hereinafter). The scenario XML of a build can be found at
``<build>/hypervisor/.scenario.xml``, where ``<build>`` is the name of the build
directory. You can make further changes to this file to adjust to your specific
requirements. Another ``make`` will rebuild the hypervisor using the updated
scenario XML.
To generate hypervisor configurations, you must build the hypervisor
individually. The following steps generate a default but complete
configuration, based on the platform selected, assuming that you are at the
top level of the acrn-hypervisor directory. The configuration file, named
``.config``, can be found under the target folder of your build.
The following commands show how to customize manually the scenario XML based on
the predefined ``INDUSTRY`` scenario for ``nuc7i7dnb`` and rebuild the
hypervisor.
.. code-block:: none
$ cd hypervisor
$ make defconfig BOARD=nuc7i7dnb SCENARIO=industry
The BOARD specified is used to select a ``defconfig`` under
``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``.
$ make BOARD=nuc7i7dnb SCENARIO=industry hvdefconfig
$ vim build/hypervisor/.scenario.xml
(Modify the XML file per your needs)
$ make
.. note::
The ``BOARD`` and ``SCENARIO`` parameters are not needed because the
information is retrieved from the corresponding ``BOARD_FILE`` and
``SCENARIO_FILE`` XML configuration files. The ``TARGET_DIR`` parameter
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.
A hypervisor build memorizes the board and scenario previously
configured. Thus, there is no need to duplicate BOARD and SCENARIO in the
second ``make`` above.
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`.