By supplementing Linux with a real-time co-kernel running
side-by-side with it. This small extension named Cobalt is
built into the Linux kernel, dealing with all time-critical
activities, such as handling interrupts, and scheduling real-time
threads. The Cobalt core has higher priority over the native kernel
In this dual kernel configuration, all the RTOS APIs Xenomai
provides interface with the Cobalt core, and only those APIs are
deemed real-time capable, including the subset of POSIX 1003.1c
services implemented by Xenomai (aka libcobalt).
By relying on the real-time capabilities of the native Linux kernel,
forming the Mercury core. Often, applications will require the
extension to be enabled in the target kernel, for delivering real-time
However, this is not mandatory, it depends on the application
requirements with respect to responsiveness and maximum jitter; some
may even tolerate a certain percentage of deadline misses.
In this single kernel configuration, all the non-POSIX RTOS APIs
Xenomai provides are accurately emulated over the native threading
library (preferably NPTL, but also supports linuxthreads for
Figure 2. Xenomai 3 single kernel configuration
Xenomai 3 supports both the single and dual kernel configurations. The
discontinued Xenomai 2 architecture only supported the dual kernel
Xenomai license terms
All Xenomai code running in kernel space is licensed under the terms
of the Linux kernel license, i.e. GPL v2.
Xenomai libraries linked to applications are licensed under the terms
of the LGPL v2.1.
For information regarding a particular software component, you should
look at the COPYING file available in the directory containing the
relevant source code.
Single or dual kernel configuration?
Assuming you know the target SoC and the application requirements
with respect to real-time guarantees, you should define which of the
single or dual kernel configurations best fits your needs. The
following hints may help:
Does your application actually have real-time requirements, and how
stringent are they? If migrating an application from an embedded
RTOS to a Linux-based platform, the question may stand because unlike
legacy RTOSes, Linux sees embedded and real-time characteristics as
orthogonal issues. Some migrated applications may even be fine with only
emulating the original RTOS API over a regular kernel and standard
preemption (CONFIG_PREEMPT). Those may benefit from Xenomai 3 in
single kernel configuration.
For stringent real-time requirements, you should consider the
availability of the hard real-time support for your target SoC
architecture and Linux kernel version.
Embedded architecture support for Xenomai in dual kernel
configuration can be viewed
technology is based on a kernel patch which introduces a
mechanism for diverting all critical events to a dual kernel
extension, coupled to the host Linux kernel. This mechanism
called the Interrupt pipeline (aka I-Pipe) is described in
details by this (slightly outdated)
I-pipe patches available for various kernel releases can be
fetched at this site.
For a single kernel configuration, the list of target
architectures supporting the full preemption features (aka
PREEMPT-RT) is available
How many CPU cores will be involved in real-time operations?
in a dual kernel configuration, the Xenomai co-kernel normally
benefits from its simpler locking scheme when dealing with
real-time activities concurrently on not more than four CPU
Beyond four CPU cores running real-time activities, SMP
scalability will be better with a single kernel configuration.
The key issue is with the number of CPU cores actually running
real-time threads and receiving interrupts from real-time sources,
not with the overall number of cores on line on the target
hardware. Because the Cobalt co-kernel does not share any lock with the
regular Linux kernel when dealing with real-time activities, a 16-way
server pinning such activities on not more than four of the available
cores would still deliver good performances in a Cobalt-based dual
Is any of those dual kernel pros critical to your case?
porting the Cobalt co-kernel to a new architecture is fairly
it is decoupled from the development cycle of the mainline
Linux kernel, thus allowing to pick the desired (or required)
kernel version more freely.
it can simplify the worst-case analysis and keeps the results
valid over update cycles of the mainline Linux kernel which
it allows to fine-tune the non-real-time part for throughput
without negative impact on the real-time job.
it does not require any tuning of the regular Linux system to
guarantee short and bounded latencies for the real-time job.
Is any of those single kernel pros critical to your case?
the stock kernel drivers can be reused by real-time applications
with no change (provided they don’t create latency issues due to
an unfortunate implementation). On the other hand, drivers need
to be specifically implemented for running over a dual kernel
configuration, i.e. over the in-kernel RTDM interface.
the programming model may be simpler than with a dual kernel
configuration, since the kernel is deemed to enforce real-time
behavior globally. This said, cautious application design and
implementation must be a common rule regardless of the
underlying real-time technology, as not all available services
may be suited for real-time usage.
all standard utilities for monitoring the system operations can
report about the real-time activities out of the box. On the
other hand, a dual kernel system has to adapt such tools
specifically for this purpose.
Do you need non-POSIX real-time APIs?
Porting legacy non-POSIX applications to POSIX may not be the best
option. Although there may be similarities, the semantics of
traditional RTOS APIs may differ significantly from POSIX in many
cases, which often makes the migration process quite painful and
Xenomai ships with emulators of traditional RTOS APIs, like
VxWorks™ and pSOS™, both available in single and dual kernel
configurations. Xenomai aims at accurately mimicking the original
services with low overhead.
However, maybe Xenomai does not provide an emulator yet for the API
you are looking for, or some services are missing from the existing
emulators, in which case you should consider raising the topic on the
e-mail discussion list. Xenomai is based on
generic building blocks for implementing RTOS APIs, so extending it is
a documented option.
Gathering the Linux kernel bits
Depending on your requirements, you will need:
a Linux kernel ported to your target SoC or platform. If possible,
prefer mainline kernel releases over
vendor-originated ones. Among other issues, kernel patches required
for running hard real-time applications over single (PREEMPT_RT) or
dual kernel (I-pipe) configurations are commonly based over mainline
for a dual kernel configuration, an
I-pipe patch fitting your
target kernel. If you don’t find any patch that matches exactly but
feel lucky, you may try applying a patch issued against a kernel only
differing by its sublevel release number, e.g. from 3.10.22 to
3.10.20. However, even if it applies cleanly, some extra testing is
required, and getting additional information from the
e-mail discussion list may help.
for a single kernel configuration with hard real-time capabilities,
patch matching your target kernel.
Getting the Xenomai sources
Xenomai 3 is the current architecture, aimed at supporting both the
single and dual kernel configurations.
The Xenomai project issues a tarball for each official
candidate release. However,
we recommend tracking our development and/or maintenance GIT trees, for
getting the latest fixes.
The Xenomai project uses GIT for managing the
source code repositories. There is no shortage of GIT crash courses,
references, howtos, tips and comprehensive documentation available
from the Internet. For the sake of conciseness, we will only mention
two documentation hubs from which you should be able to find your way:
contains instructions for building and installing Xenomai 3.x.
If something goes wrong
First and foremost, please make sure to have a look at the appropriate
troubleshooting guide, whether you are using a
If running any release from the discontinued Xenomai 2 series, or a
Xenomai 3 release using the Cobalt real-time core, then you are
running a dual kernel configuration. Xenomai 3 over the Mercury
core stands for a single kernel configuration.
If still out of luck, and if your favorite Internet search engine did
not help finding a similar/same problem already solved for another
user, then you should try raising the issue on the
main e-mail discussion list.
How to ask for help on the mailing list
To maximize your chances of receiving quick and accurate responses to
your request for help, you really want to follow
Embedded Linux distributions & Xenomai
The Yocto-based Embedded Linux
Development Kit (aka ELDK) includes pre-built GNU cross-development
tools and bootable root file systems for a variety of ARM™,
PowerPC™ and MIPS™ embedded target systems. It also ships with a
pre-built stable Xenomai release.
The following books and articles describe different aspects of the