Skip to content
GitLab

Start_Here · Changes

Page history
rework documentation structure, fix markup authored by Philippe Gerum's avatar Philippe Gerum
Hide whitespace changes
Inline Side-by-side
Start_Here.asciidoc 0 → 100644
View page @ b796ebca
:toc:
Start Here
==========
Supported hardware
------------------
Xenomai is supported on a variety of hardware. The ports we know about
are link:Supported_Hardware[listed here].
How does Xenomai deliver real-time?
-----------------------------------
There are two options:
[[cobalt]]
- 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
activities.
+
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_).
.Xenomai 3 dual kernel configuration
image::./figures/x3-cobalt-interfaces.png["Cobalt interfaces", align="center"]
[NOTE]
Cobalt is an evolution of the former
link:Introducing_Xenomai_3#Motivation_for_a_major_evolution[Xenomai 2 architecture].
[[mercury]]
- By relying on the real-time capabilities of the native Linux kernel,
forming the *Mercury* core. Often, applications will require the
https://www.osadl.org/Realtime-Linux.projects-realtime-linux.0.html[PREEMPT-RT]
extension to be enabled in the target kernel, for delivering real-time
services.
+
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
legacy setups).
.Xenomai 3 single kernel configuration
image::./figures/x3-mercury-interfaces.png["Mercury interfaces", align="center"]
[NOTE]
Xenomai 3 supports both the single and dual kernel configurations. The
discontinued Xenomai 2 architecture only supported the dual kernel
configuration.
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.
Preparation checklist
---------------------
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.
** Hardware support for Xenomai in dual kernel configuration can
be viewed link:Supported_Hardware[here]. This 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 (outdated) link:Life_With_Adeos[document]. All I-pipe
patches available for various kernel releases can be fetched
link:/downloads/ipipe/[at this site].
** For a single kernel configuration, the list of target
architectures supporting the full preemption features (aka
_PREEMPT-RT_) is available
https://www.osadl.org/Realtime-Linux.projects-realtime-linux.0.html[here].
* 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
cores.
** Beyond four CPU cores running real-time activities, SMP
scalability will be better with a single kernel configuration.
[NOTE]
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
kernel configuration.
- Is any of those dual kernel pros critical to your case?
* porting the Cobalt co-kernel to a new architecture is fairly
simple.
* 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
hosts it.
* 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
error-prone.
Xenomai ships with emulators of traditional RTOS APIs, like
VxWorks(TM) and pSOS(TM), 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
link:Mailing_Lists[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 ftp://ftp.kernel.org/pub/[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
kernels.
- for a dual kernel configuration, an
link:/downloads/ipipe/[_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
link:Mailing_Lists[e-mail discussion list] may help.
- for a single kernel configuration with hard real-time capabilities,
a https://www.kernel.org/pub/linux/kernel/projects/rt/[PREEMPT-RT
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.
.Accessing the development tree of Xenomai 3.x
**********************************************
git://git.xenomai.org/xenomai-3.git +
https://git.xenomai.org/xenomai-3.git +
http://git.xenomai.org/xenomai-3.git
**********************************************
[NOTE]
The Xenomai project issues a tarball for each official
link:/downloads/xenomai/stable/[stable] or
link:/downloads/xenomai/testing/[candidate] release. However,
we recommend tracking our development and/or maintenance GIT trees, for
getting the latest fixes.
Using GIT
^^^^^^^^^
The Xenomai project uses http://git-scm.com/[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:
- http://git-scm.com/documentation[The GIT project documentation hub].
- https://git.wiki.kernel.org/index.php/GitDocumentation[The GIT documentation wiki].
In addition, let's mention a simple tutorial for bootstrapping with
GIT and day-to-day usage:
https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
Building Xenomai from sources
-----------------------------
- link:Installing_Xenomai_3[This document]
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
link:Troubleshooting[troubleshooting guide].
[TIP]
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
link:Mailing_Lists[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
link:Getting_Help[these recommendations].
*******************************************************************
Embedded Linux distributions & Xenomai
--------------------------------------
- The Yocto-based http://www.denx.de/wiki/DULG/ELDK[Embedded Linux
Development Kit] (aka _ELDK_) includes pre-built GNU cross-development
tools and bootable root file systems for a variety of ARM(TM),
PowerPC(TM) and MIPS(TM) embedded target systems. It also ships with a
pre-built stable Xenomai release.
History of the Xenomai project
------------------------------
link:History[This document] provides a brief history of the Xenomai
project, from its inception in 2001 to the recent years.
Other readings
--------------
The following books and articles describe different aspects of the
Xenomai technology:
- http://www.denx.de/en/pub/News/Xum2009AbstractsAndPresentations/Xenomai_and_Realtime_Image_Processing_Control.pdf[Image
processing with Xenomai 2 by Xerox UK], presented at the http://www.denx.de/en/News/XenomaiUserMeeting2009[Xenomai User Meeting '09].
- https://www.amazon.com/Building-Embedded-Linux-Systems-Techniques/dp/0596529686[Building Embedded
Linux Systems, Second Edition]. This book dedicates a chapter
explaining the dual kernel architecture of Xenomai 2.
- http://xenomai.org/documentation/slides/Xenomai-OSMB-2007-01.pdf[Xenomai: the
RTOS Chameleon for Linux], at Open Source Meets Business, Nürnberg,
Germany, January 2007.
- http://www.isde.uni-hannover.de/images/b/b3/ELROB_TechnicalPaper_RTS_University_of_Hannover.pdf[Semi-autonomous service robots] at the ELROB 2006.

Imprint & Privacy Policy