mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-05-03 14:06:54 +00:00
bc099a7e71
This patch adds explanations and examples of the makefile targets for hypervisor configuration, including `hvdefconfig`, `hvshowconfig`, `hvdiffconfig` and `hvapplydiffconfig`. Tracked-On: #5644 Signed-off-by: Junjie Mao <junjie.mao@intel.com> Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
264 lines
8.8 KiB
ReStructuredText
264 lines
8.8 KiB
ReStructuredText
.. _getting-started-building:
|
|
|
|
Build ACRN From Source
|
|
######################
|
|
|
|
Following a general embedded-system programming model, the ACRN
|
|
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 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 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.
|
|
|
|
- **Reduce complexity.** ACRN is a lightweight reference hypervisor, built for
|
|
embedded IoT. As new platforms for embedded systems are rapidly introduced,
|
|
support for one binary could require more and more complexity in the
|
|
hypervisor, which is something we strive to avoid.
|
|
|
|
- **Maintain small footprint.** Implementing dynamic parsing introduces
|
|
hundreds or thousands of lines of code. Avoiding dynamic parsing
|
|
helps keep the hypervisor's Lines of Code (LOC) in a desirable range (less
|
|
than 40K).
|
|
|
|
- **Improve boot time.** Dynamic parsing at runtime increases the boot
|
|
time. Using a build-time configuration and not dynamic parsing
|
|
helps improve the boot time of the hypervisor.
|
|
|
|
|
|
Build the ACRN hypervisor, device model, and tools from source by following
|
|
these steps.
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 1
|
|
|
|
.. _install-build-tools-dependencies:
|
|
|
|
.. rst-class:: numbered-step
|
|
|
|
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 steps to
|
|
configure and build ACRN natively on **Ubuntu 18.04 or newer**.
|
|
|
|
The following commands install the necessary tools for configuring and building
|
|
ACRN.
|
|
|
|
.. code-block:: none
|
|
|
|
$ sudo apt install gcc \
|
|
git \
|
|
make \
|
|
libssl-dev \
|
|
libpciaccess-dev \
|
|
uuid-dev \
|
|
libsystemd-dev \
|
|
libevent-dev \
|
|
libxml2-dev \
|
|
libusb-1.0-0-dev \
|
|
python3 \
|
|
python3-pip \
|
|
libblkid-dev \
|
|
e2fslibs-dev \
|
|
pkg-config \
|
|
libnuma-dev \
|
|
liblz4-tool \
|
|
flex \
|
|
bison \
|
|
xsltproc
|
|
|
|
$ 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/
|
|
|
|
.. rst-class:: numbered-step
|
|
|
|
Get the ACRN Hypervisor Source Code
|
|
***********************************
|
|
|
|
The `ACRN hypervisor <https://github.com/projectacrn/acrn-hypervisor/>`_
|
|
repository contains four main components:
|
|
|
|
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:
|
|
|
|
.. code-block:: none
|
|
|
|
$ git clone https://github.com/projectacrn/acrn-hypervisor
|
|
|
|
|
|
.. _build-with-acrn-scenario:
|
|
|
|
.. rst-class:: numbered-step
|
|
|
|
Build With the ACRN Scenario
|
|
****************************
|
|
|
|
Currently, the ACRN hypervisor defines these typical usage scenarios:
|
|
|
|
SDC:
|
|
The SDC (Software Defined Cockpit) scenario defines a simple
|
|
automotive use case that includes one pre-launched Service VM and one
|
|
post-launched User VM.
|
|
|
|
LOGICAL_PARTITION:
|
|
This scenario defines two pre-launched VMs.
|
|
|
|
INDUSTRY:
|
|
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.
|
|
|
|
HYBRID:
|
|
This scenario defines a hybrid use case with three VMs: one
|
|
pre-launched Safety VM, one pre-launched Service VM, and one post-launched
|
|
Standard VM.
|
|
|
|
HYBRID_RT:
|
|
This scenario defines a hybrid use case with three VMs: one
|
|
pre-launched RTVM, one pre-launched Service VM, and one post-launched
|
|
Standard VM.
|
|
|
|
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:
|
|
|
|
.. note::
|
|
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``:
|
|
|
|
.. code-block:: none
|
|
|
|
$ make BOARD=nuc7i7dnb SCENARIO=industry
|
|
|
|
* Build the release version of ``HYBRID`` scenario on the ``whl-ipc-i5``:
|
|
|
|
.. code-block:: none
|
|
|
|
$ make BOARD=whl-ipc-i5 SCENARIO=hybrid RELEASE=y
|
|
|
|
* Build the release version of ``HYBRID_RT`` scenario on the ``whl-ipc-i7``
|
|
(hypervisor only):
|
|
|
|
.. code-block:: none
|
|
|
|
$ make BOARD=whl-ipc-i7 SCENARIO=hybrid_rt RELEASE=y hypervisor
|
|
|
|
* Build the release version of the device model and tools:
|
|
|
|
.. code-block:: none
|
|
|
|
$ make RELEASE=y devicemodel tools
|
|
|
|
You can also build ACRN with your customized 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
|
|
|
|
Modify the Hypervisor Configuration
|
|
***********************************
|
|
|
|
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.
|
|
|
|
The following commands show how to customize manually the scenario XML based on
|
|
the predefined ``INDUSTRY`` scenario for ``nuc7i7dnb`` and rebuild the
|
|
hypervisor. The ``hvdefconfig`` target generates the configuration files without
|
|
building the hypervisor, allowing users to tweak the configurations.
|
|
|
|
.. code-block:: none
|
|
|
|
$ make BOARD=nuc7i7dnb SCENARIO=industry hvdefconfig
|
|
$ vim build/hypervisor/.scenario.xml
|
|
(Modify the XML file per your needs)
|
|
$ make
|
|
|
|
.. note::
|
|
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 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.
|
|
|
|
Descriptions of each configuration entry in scenario XML files are also
|
|
available at :ref:`scenario-config-options`.
|