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 Modify the 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.

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.

sudo apt install gcc \
     git \
     make \
     libssl-dev \
     libpciaccess-dev \
     uuid-dev \
     libsystemd-dev \
     libevent-dev \
     libxml2-dev \
     libxml2-utils \
     libusb-1.0-0-dev \
     python3 \
     python3-pip \
     libblkid-dev \
     e2fslibs-dev \
     pkg-config \
     libnuma-dev \
     liblz4-tool \
     flex \
     bison \
     xsltproc \
     clang-format

sudo pip3 install lxml xmlschema

wget https://acpica.org/sites/acpica/files/acpica-unix-20210105.tar.gz
tar zxvf acpica-unix-20210105.tar.gz
cd acpica-unix-20210105
make clean && make iasl
sudo cp ./generate/unix/bin/iasl /usr/sbin/

Get the ACRN Hypervisor Source Code

The ACRN hypervisor repository contains four main components:

  1. The ACRN hypervisor code is in the hypervisor directory.

  2. The ACRN device model code is in the devicemodel directory.

  3. The ACRN debug tools source code is in the misc/debug_tools directory.

  4. The ACRN online services source code is in the misc/services directory.

Enter the following to get the ACRN hypervisor source code:

git clone https://github.com/projectacrn/acrn-hypervisor

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:

    make BOARD=nuc7i7dnb SCENARIO=industry

  • Build the release version of HYBRID scenario on the whl-ipc-i5:

    make BOARD=whl-ipc-i5 SCENARIO=hybrid RELEASE=y

  • Build the release version of HYBRID_RT scenario on the whl-ipc-i7 (hypervisor only):

    make BOARD=whl-ipc-i7 SCENARIO=hybrid_rt RELEASE=y hypervisor

  • Build the release version of the device model and tools:

    make RELEASE=y devicemodel tools

You can also build ACRN with your customized scenario:

  • Build with your own scenario configuration on the nuc11tnbi5, assuming the scenario is defined in /path/to/scenario.xml:

    make BOARD=nuc11tnbi5 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:

    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 Supported Hardware document for information about platform needs for each scenario. For more instructions to customize scenarios, see Modify the Hypervisor Configuration and Introduction to ACRN Configuration.

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.

$ 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

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.

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 Use the ACRN Configuration Editor for more instructions.

Descriptions of each configuration entry in scenario XML files are also available at Scenario Configuration Options.