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 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 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 running in user-space, so that the latter can submit well-formed system calls to the former. In other words, to build, 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_HIGH_PERCPU_CONCURRENCY N Optimizes the implementation for applications with many real-time threads running concurrently on any given CPU core
CONFIG_EVL_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_NR_OBSERVABLES 64 Maximum number of EVL observables (does not include threads)
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).
CONFIG_GPIOLIB_OOB n Enable support for out-of-band GPIO line handling requests.
CONFIG_SPI_OOB, CONFIG_SPIDEV_OOB n Enable support for out-of-band SPI transfers.

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. For arm64, you need to turn on CONFIG_COMPAT and CONFIG_COMPAT_VDSO in the kernel configuration. To be allowed to change the latter, the CROSS_COMPILE_COMPAT environment variable should be set to the prefix of the 32-bit ARMv7 toolchain which should be used to compile the vDSO (yes, this is quite convoluted). For instance:

$ make <your-make-args> ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- CROSS_COMPILE_COMPAT=arm-linux-gnueabihf- (x|g|menu)config

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 system binaries to $DESTDIR in the process
install_all install, copying all the generated binaries including the tidbits

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


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


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: Mon, 21 Jun 2021 14:06:41 CEST