Installing Xenomai 2.6.2.1

Starting with version 2.1, Xenomai follows a split source model, decoupling the kernel space support from the user-space libraries used in accessing the former.

To this end, kernel and user-space Xenomai components are respectively available under the ksrc/ and src/ sub-trees.

The ksrc/ sub-tree providing the kernel space support is seen as a built-in extension of the Linux kernel, and no more as a collection of separate out-of-tree modules. A direct benefit of such approach is the ability to build the Xenomai real-time subsystem statically into the target kernel, or as loadable modules as with earlier versions. therefore, the usual Linux kernel configuration process will be normally used to define the various settings for the Xenomai kernel components. Sections "Preparing the target kernel" and "Configuring and building the kernel" document the installation process of this kernel space support.

The src/ sub-tree contains the various user-space libraries and commands provided by the Xenomai framework. This tree can be built separately from the kernel support, even if the latter is absent from the build system. Section "Building the user-space support" documents the installation process of this user-space support.

If you are using a Debian based distribution, it is also possible to install, and even build Xenomai as a set of Debian packages. For further details, see this page.

Xenomai provides a real-time sub-system seamlessly integrated to Linux, therefore the first step is to build it as part of the target kernel. To this end, scripts/prepare-kernel.sh is a shell script which sets up the target kernel properly. The syntax is as follows:

For instance, the following command would prepare the Linux tree located at /usr/src/linux-2.6.23-ipipe in order to include the Xenomai support:

Note: The script will infer the location of the Xenomai kernel code from its own location within the Xenomai source tree. In other words, if /usr/src/xenomai-2.4/script/prepare-kernel.sh is executing, then Xenomai’s kernel support available from /usr/src/xenomai-2.4/ksrc will be bound to the target kernel.

Once the target kernel has been prepared, the kernel should be configured following its usual configuration procedure. All Xenomai configuration options are available from the "Real-time subsystem" toplevel menu.

There are several important kernel configuration options, some are documented in the TROUBLESHOOTING guide, others in the "Typical installation procedures" for the architecture you are using.

Once configured, the kernel should be built as usual.

If you want several different configs/builds at hand, you can reuse the same source by adding O=../build-<target> to each make invocation. See section "Building for the PowerPC architecture" for an example

In order to cross-compile the Linux kernel, pass an ARCH and CROSS_COMPILE variable on make command line. See sections "Building for the PowerPC architecture", "Building for the Blackfin", "Building for ARM" and "Building for NIOS II" for examples.

A regular autoconf script is provided in order to prepare for building the user-space support. The options listed below can be passed to this script. Those options only affect the libraries compiled as part of Xenomai’s user-space support, but in any case, they never impact the kernel-based support.

Because of the strong decoupling between the kernel and user-space build procedures, Xenomai needs to make sure that all user-space options selected at configuration time will be consistent with the actual support the runtime libraries will get from the target kernel. For instance, enabling TSC support in user-space for x86 albeit the kernel has been compiled with CONFIG_X86_TSC disabled would certainly lead to runtime problems if uncaught, since Xenomai and the application would not agree on the high precision clock to use for their timings. Furthermore, most of these issues cannot be probed for during compilation, because the target generally has different features than the host, even when they are the same arch (ex 386 vs 686).

In order to solve those potential issues, each Xenomai architecture port defines a set of critical features which is tested for consistency, each time a user-space application binds itself to a real-time interface in kernel space. Unresolvable conflicts are reported and the execution stops immediately in such a case.

Options that need perfect matching between both sides are marked as "strong" in the following lists, others that may differ are marked as "weak". The way Xenomai deals with tolerated discrepancies is decided on a case-by-case basis, depending on the option considered. When not applicable, the binding type remains unspecified.

For instance, UP and SMP-enabled kernels can run either UP or SMP-enabled user-space applications indifferently, since the SMP option’s binding is weak. On the other hand, x86-based applications linked against Xenomai libraries which have been compiled with the x86-tsc option on, must run on a kernel built with CONFIG_X86_TSC set, since the x86-tsc option’s binding is strong.

In order to cross-compile Xenomai user-space support, you will need to pass a --host and --build option to the configure script. The --host option allow to select the architecture for which the libraries and programs are built. The --build option allows to choose the architecture on which the compilation tools are run, i.e. the system running the configure script.

Since cross-compiling requires specific tools, such tools are generally prefixed with the host architecture name; for example, a compiler for the power PC architecture may be named powerpc-405-linux-gnu-gcc.

When passing the option --host=powerpc-405-linux-gnu to configure, configure will automatically use powerpc-405-linux-gnu- as a prefix to all compilation tools names and infer the host architecture name from this prefix. If configure is unable to infer the architecture name from the cross-compilation tools prefix, you will have to manually pass the name of all compilation tools using at least the CC and LD, variables on configure command line. See sections "Building for the PowerPC architecture" and "Building for the Blackfin" for an example using the CC and LD variable, or "Building for ARM" for an example using the --host argument.

The easiest way to build a GNU cross-compiler might involve using crosstool-ng, available here.

If you want to avoid to build your own cross compiler, you might if find easier to use the ELDK. It includes the GNU cross development tools, such as the compilers, binutils, gdb, etc., and a number of pre-built target tools and libraries necessary to provide some functionality on the target system. See here for further details.

Some other pre-built toolchains:

The examples in following sections use the following conventions:

Since Linux 2.6.24, x86_32 and x86_64 trees are merged. Therefore, building Xenomai for 2.6.24 or later is almost the same, regardless of the 32/64bit issue. You should note, however, that it is not possible to run xenomai libraries compiled for x86_32 with a kernel compiled for x86_64.

Assuming that you want to build natively for a x86_64 system (x86_32 cross-build options from x86_64 appear between brackets), you would typically run:

…configure the kernel (see also the recommended settings here).

Enable Xenomai options, then install as needed with:

Now, let’s say that you really want to build Xenomai for a Pentium-based x86 32bit platform running a legacy 2.6.23 kernel, using the native host toolchain; the typical steps would be as follows:

…configure the kernel (see also the recommended settings here).

Enable Xenomai options, then install as needed with:

Similarly, for a legacy kernel on a 64bit platform, you would use:

…configure the kernel (see also the recommended settings here).

Enable Xenomai options, then install as needed with:

Once the compilation has completed, /usr/xenomai should contain the user-space librairies and header files you would use to build applications that call Xenomai’s real-time support in kernel space.

The remaining examples illustrate how to cross-compile Xenomai for various architectures. Of course, you will have to install the proper cross-compilation toolchain for the target system first, in order to build Xenomai.

PowerPC has a legacy arch/ppc branch, and a newer, current arch/powerpc tree. Xenomai supports both, but using arch/powerpc is definitely recommended. To help the preparation script to pick the right one, you have to specify either --arch=powerpc (current) or --arch=ppc (legacy). Afterwards, the rest should be a no-brainer:

A typical cross-compilation setup, in order to build Xenomai for a lite5200 board running a recent 2.6.29.4 kernel. We use DENX’s ELDK cross-compiler:

…select the kernel and Xenomai options, save the configuration

…manually install the u-boot image and modules to the proper location

Another cross-compilation setup, in order to build Xenomai for a powerpc64 PA-Semi board running a recent 2.6.29.4 kernel:

…select the kernel and Xenomai options, save the configuration

…manually install the vmlinux image and modules to the proper location

Yet another cross-compilation setup, this time for building Xenomai for a PowerPC-405-based system running a legacy arch/ppc 2.6.14 kernel (we do support recent ones as well on this platform):

…select the kernel and Xenomai options, save the configuration

…manually install the kernel image, system map and modules to the proper location

The Blackfin is an MMU-less, DSP-type architecture running uClinux.

…select the kernel and Xenomai options, then compile with:

…then install as needed

…build the user-space support

You may also want to have a look at the hands-on description about configuring and building a Xenomai system for the Blackfin architecture, available at this address.

Using codesourcery toolchain named arm-none-linux-gnueabi-gcc and compiling for a CSB637 board (AT91RM9200 based), a typical compilation will look like:

…manually install the kernel image, system map and modules to the proper location

It is possible to build for an older architecture version (v6 instead of v7, or v4 instead of v5), if your toolchain does not support the target architecture, the only restriction being that if SMP is enabled, the architecture should not be less than v6.

NIOS II is a softcore processor developped by Altera and is dedicated to the Altera’s FPGA circuits.

NIOS II with no MMU enabled is supported by the uClinux distribution.

You have to start with a minimal system with at least:

Note in Linux, IRQ 0 means auto-detected, so you must not use IRQ 0 for ANY devices.

The Xenomai port for NIOS II uses extra hardware that you have to add in SOPC builder:

You have to use Altera’s Quartus II version 9.0 at least for synthesis.

A good start for your design is to use reference design shipped with your target board.

For example, with an Altera’s board, you may use the standard design. Standard reference designs for Altera’s boards are available here.

You should first verify that uClinux without Xenomai can run on the target board.

The typical actions for building the uClinux kernel for NIOS II (available here) are:

If $uClinux-dist is the path of NIOS II uClinux release, for example:

/home/test/nios2-linux/uClinux-dist

If the NIOS II cross-compiler is called nios2-linux-gcc, a typical compilation will look like:

In order to test the Xenomai installation, you should first try to boot the patched kernel. The kernel boot logs should show messages like:

Where <arch> is the architecture you are using. If the kernel fails to boot, or the log messages indicates an error status instead, see the TROUBLESHOOTING guide.

In order to test Xenomai user-space support, launch the latency test:

The latency test should display a message every second with minimal, maximal and average latency values, such as:

If the latency test displays an error message, hangs, or displays unexpected values, see the TROUBLESHOOTING guide.

If the latency test succeeds, you should try next to run a latency test under load to evaluate the latency test of your system, the xeno-test script allows doing that. Try: