Building EVL

Building EVL from source

The build process. Building EVL from the source code is a two-step process: we need to build a kernel enabling the EVL core, and the library implementing the user API to this core - aka libevl - using the proper toolchain. These steps may happen in any order. The output of this process is:

  • a Linux kernel image featuring Dovetail and the EVL core on top of it.

  • the libevl.so shared library* which enables applications to request services from the EVL core, along with a few basic utilities and test programs.

* The static archive libevl.a is generated as well.

Getting the sources

EVL sources are maintained in two separate GIT repositories. As a preliminary step, you may want to have a look at the EVL development process, in order to determine which GIT branches you may be interested in these repositories:

Other prerequisites

In addition to the source code, we need:

  • a GCC toolchain for the target CPU architecture.

  • the UAPI headers from the target Linux kernel fit with the EVL core. Each UAPI file exports a set of definitions and interface types which are shared with libevl.so running in user-space, so that the latter can submit well-formed system calls to the former. In other words, to build libevl.so, we need access to the contents of include/uapi/asm/ and include/uapi/evl/ from a source kernel tree which contains the EVL core which is going to handle the system calls.

libevl relies on thread-local storage support (TLS), which might be broken in some obsolete (ARM) toolchains. Make sure to use a current one.

Building the core

Once your favorite kernel configuration tool is brought up, you should see the EVL configuration block somewhere inside the General setup menu. This configuration block looks like this:

Alt text

Enabling CONFIG_EVL should be enough to get you started, the default values for other EVL settings are safe to use. You should make sure to have CONFIG_EVL_LATMUS and CONFIG_EVL_HECTIC enabled too; those are drivers required for running the latmus and hectic utilities available with libevl, which measure latency and validate the context switching sanity.

If you are unfamiliar with building kernels, this document may help. If you face hurdles building directly into the kernel source tree as illustrated in the document mentioned, you may want to check whether building out-of-tree might work, since this is how Dovetail/EVL developers usually rebuild kernels. If something goes wrong while building in-tree or out-of-tree, please send a note to the EVL mailing list with the relevant information.

All core configuration options

Symbol name Default Purpose
CONFIG_EVL N Enable the EVL core
CONFIG_EVL_SCHED_QUOTA N Enable the quota-based scheduling policy
CONFIG_EVL_SCHED_TP N Enable the time-partitioning scheduling policy
CONFIG_EVL_SCHED_TP_NR_PART N Number of time partitions for CONFIG_EVL_SCHED_TP
CONFIG_EVL_SCHED_RUNSTATS Y Collect runtime statistics about threads
CONFIG_EVL_COREMEM_SIZE 2048 Size of the core memory heap (in kilobytes)
CONFIG_EVL_NR_THREADS 256 Maximum number of EVL threads
CONFIG_EVL_NR_MONITORS 512 Maximum number of EVL monitors (i.e. mutexes + semaphores + flags + events)
CONFIG_EVL_NR_CLOCKS 8 Maximum number of EVL clocks
CONFIG_EVL_NR_XBUFS 16 Maximum number of EVL cross-buffers
CONFIG_EVL_NR_PROXIES 64 Maximum number of EVL proxies
CONFIG_EVL_LATENCY_USER 0 Pre-set core timer gravity value for user threads (0 means use pre-calibrated value)
CONFIG_EVL_LATENCY_KERNEL 0 Pre-set core timer gravity value for kernel threads (0 means use pre-calibrated value)
CONFIG_EVL_LATENCY_IRQ 0 Pre-set core timer gravity value for interrupt handlers (0 means use pre-calibrated value)
CONFIG_EVL_DEBUG N Enable debug features
CONFIG_EVL_DEBUG_CORE N Enable core debug assertions
CONFIG_EVL_DEBUG_CORE N Enable core debug assertions
CONFIG_EVL_DEBUG_MEMORY N Enable debug checks in core memory allocator. **This option adds a significant overhead affecting latency figures**
CONFIG_EVL_DEBUG_WOLI N Enable warn-on-lock-inconsistency checkpoints
CONFIG_EVL_WATCHDOG Y Enable watchdog timer
CONFIG_EVL_WATCHDOG_TIMEOUT 4 Watchdog timeout value (in seconds)

Enabling 32-bit support in a 64-bit kernel (CONFIG_COMPAT)

Starting from EVL ABI 20 in the v5.6 series, the EVL core generally allows 32-bit applications to issue system calls to a 64-bit kernel when both the 32 and 64-bit CPU architectures are supported, such as ARM (aka Aarch32) code running over an arm64 (Aarch64) kernel. In the latter case, you have to enable support for the 32-bit vDSO segment by enabling CONFIG_COMPAT_VDSO in the kernel configuration in addition to CONFIG_COMPAT. Next, you have to mention the 32-bit ARM toolchain which should be used to compile it by setting the CROSS_COMPILE_COMPAT environment variable the kernel build system expects, as illustrated below:

$ make <your-make-args> ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- CROSS_COMPILE_COMPAT=arm-linux-gnueabihf-

For instance, if you plan to run EVL over any of the Raspberry PI 64-bit computers, you may find useful to use the PI-centric 32-bit Linux distributions readily available such as Raspbian. To do so, make sure to enable CONFIG_COMPAT and CONFIG_COMPAT_VDSO for your EVL-enabled kernel, building the 32-bit vDSO alongside as mentioned earlier.

Building libevl

The generic command for building libevl is:

$ make [-C $SRCDIR] [ARCH=$cpu_arch] [CROSS_COMPILE=$toolchain] UAPI=$uapi_dir [OTHER_BUILD_VARS] [goal...]

Main build variables

Variable Description
$SRCDIR Path to this source tree
$cpu_arch CPU architecture you build for (‘arm’, ‘arm64’, ‘x86’)
$toolchain Optional prefix of the binutils filename (e.g. ‘arm-linux-gnueabihf-’, ‘aarch64-linux-gnu-’)

Other build variables

Variable Description Default
D={0|1} Disable or enable debug build, i.e. -g -O0 vs -O2 0
O=$output_dir Generate binary output files into $output_dir .
V={0|1} Set build verbosity level, 0 is terse 0
DESTDIR=$install_dir Install library and binaries into $install_dir /usr/evl

Make goals

Goal Action
all generate all binaries (library, utilities and tests)
clean remove the build files
install do all, copying the generated binaries to $DESTDIR in the process

Cross-compiling EVL

Let’s say the library source code is located at ~/git/libevl, and the kernel sources featuring the EVL core is located at ~/git/linux-evl.

Cross-compiling EVL and installing the resulting library and utilities to a staging directory located at /nfsroot/<machine>/usr/evl would amount to this:

Cross-compiling from a separate build directory

# First create a build directory the where output files should go
$ mkdir /tmp/build-imx6q && cd /tmp/build-imx6q
# Then start the build+install process
$ make -C ~/git/libevl O=$PWD ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- UAPI=~/git/linux-evl DESTDIR=/nfsroot/imx6q/usr/evl install

or,

Cross-compiling from the EVL library source tree

$ mkdir /tmp/build-hikey
$ cd ~/git/libevl
$ make O=/tmp/build-hikey ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- UAPI=~/git/linux-evl DESTDIR=/nfsroot/hikey/usr/evl install

This is good practice to always generate the build output files to a separate build directory using the O= directive on the make command line, not to clutter your source tree with those. Generating output to a separate directory also creates convenience Makefiles on the fly in the output tree, which you can use to run subsequent builds without having to mention the whole series of variables and options on the make command line again.

Native EVL build

Conversely, you may want to build EVL natively on the target system. Installing the resulting library and utilities directly to their final home located at e.g. /usr/evl can be done as follows:

Building natively from a build directory

$ mkdir /tmp/build-native && cd /tmp/build-native
$ make -C ~/git/libevl O=$PWD UAPI=~/git/linux-evl DESTDIR=/usr/evl install

or,

Building natively from the EVL library source tree

$ mkdir /tmp/build-native
$ cd ~/git/libevl
$ make O=/tmp/build-native UAPI=~/git/linux-evl DESTDIR=/usr/evl install

Testing the installation

At this point, you really want to test the EVL installation.


Last modified: Tue, 31 Mar 2020 17:34:32 CEST