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.
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 $ 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/
The ACRN hypervisor repository contains four main components:
The ACRN hypervisor code is in the
The ACRN device model code is in the
The ACRN debug tools source code is in the
The ACRN online services source code is in the
Enter the following to get the ACRN hypervisor source code:
$ git clone https://github.com/projectacrn/acrn-hypervisor
Currently, the ACRN hypervisor defines these typical usage scenarios:
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.
This scenario defines two pre-launched 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.
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.
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
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 debug version is built by default. To build a release version,
RELEASE=y explicitly, regardless of whether a previous
Build the debug version of
INDUSTRYscenario on the
$ make BOARD=nuc7i7dnb SCENARIO=industry
Build the release version of
HYBRIDscenario on the
$ make BOARD=whl-ipc-i5 SCENARIO=hybrid RELEASE=y
Build the release version of
HYBRID_RTscenario on the
$ 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
nuc6cayh, assuming the scenario is defined in
$ make BOARD=nuc6cayh SCENARIO=/path/to/scenario.xml
Build with your own board and scenario configuration, assuming the board and scenario XML files are
$ make BOARD=/path/to/board.xml SCENARIO=/path/to/scenario.xml
ACRN uses XML files to summarize board characteristics and scenario
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
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
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
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> is the name of the build
directory. You can make further changes to this file to adjust to your specific
make will rebuild the hypervisor using the updated
The following commands show how to customize manually the scenario XML based on
INDUSTRY scenario for
nuc7i7dnb and rebuild 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
A hypervisor build remembers the board and scenario previously
configured. Thus, there is no need to duplicate BOARD and SCENARIO in the
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.