Getting Started
From Xenomai
Contents |
Introduction
This document aims at providing a better "out of the box" experience to newcomers to the Xenomai project. Although lot's of documentation is already available on the website, the different steps needed to become familiar with the technology are not necessarily obvious.
This document may be considered as an entry point, giving a brief technical background, most useful pointers for hardware bring-up and installation of the software as well as a more in-depth documentation that you may want to refer to later on.
What is Xenomai?
Xenomai is a real-time development framework cooperating with the Linux kernel, in order to provide a pervasive, interface-agnostic, hard real-time support to user-space applications, seamlessly integrated into the GNU/Linux environment.
Xenomai is based on an abstract RTOS core, usable for building any kind of real-time interfaces, over a nucleus which exports a set of generic RTOS services. Any number of RTOS personalities called "skins" can then be built over the nucleus, providing their own specific interface to the applications, by using the services of a single generic core to implement it.
Xenomai runs over seven architectures (namely ppc, blackfin, arm, x86, x86_64, ia64 and ppc64), a variety of embedded and server platforms, and can be coupled to two major Linux kernel versions (2.4 and 2.6), for MMU-enabled and MMU-less systems. Supported real-time APIs include POSIX 1003.1b, VxWorks, pSOS+, VRTX and uITRON.
Xenomai is implemented over Adeos (co-kernel approach) but also over PREEMPT_RT (native preemption).
The first approach is based on Adeos (also called I-pipe), a lightweight and mature real-time enabling layer for the Linux kernel, which is available for various architectures at low engineering and maintenance cost. Porting the I-pipe to a new architecture is fairly simple, and the overhead induced by this simple and straightforward interrupt virtualization layer is small.
Xenomai also leverages the real-time preemption patch (see A realtime preemption overview), which enhances the determinism of mainline Linux. Xenomai aims at making use of this interesting capability once the development settled and more central components got merged into mainline. A first implementation exists through the Xenomai Solo emulation engine, which allows Linux to gain native RTOS emulation layer. The Xenomai Solo source code is available from Denx software git repository.
For more information about the roadmap of the project, please to read the roadmap page in order to understand the background of the project, the mostly used Xenomai implementation (aka Xenomai 2 i.e. over Adeos) as well as the evolution of the project i.e. Xenomai 3 leveraging native preemption.
Where to start?
If you are completely new to Xenomai, a good sequence of actions is probably:
- To go through this Getting Started guide.
- To read technical articles that will give you a good idea of the underlying technology:
- To download the latest stable release.
- To get Xenomai up and running for your board (see Installing Xenomai).
- To start using the different testing tools: <install_dir>/bin (xeno-test).
- To compile and run the examples directory: <xenomai>/examples (posix/satch for instance).
Installing Xenomai
Installation from scratch
Xenomai distribution contains a README.INSTALL file that you will want to refer to in order to successfully install the software. A version of this file is also available on the website: see installation procedure.
Binary installation
Debian installation
Other distribution
Introduction to latency
Xenomai Simulator
The Xenomai project integrates a simulator based on an event-driven simulation engine. It does not rely on the host's "wall clock" but instead provides its own simulated timeline to schedule the events that occur within a system. A given test scenario can then be repeated very simply an infinite number of times, with no perturbation from the outside world (e.g. the current load of the host and so on).
The simulator is currently a tool mainly for the Xenomai project developer. As such:
- it is only maintained for the head branch and not for stable branches;
- no support will be provided (see support section).
That said, if you really want to build the simulator, a good advice is to install an older distribution (Debian Sarge or an equivalent distribution is known to work) in a Qemu or Virtualbox. Refer to the simulator installation procedure and proceed to the installation inside this simulated environment. The advantage is this you won't have to cope with compiler issues or Tcl/Tk/Tix versions of libraries that are the most common issues encountered, while building the simulator.
References for programmer
If you are a developer and that you want to start implementing your own skin and/or application on top of Xenomai, you can refer to the following documentation:
How to implement a new skin
Once you are familiar with Xenomai environment as well as with the internals, you may want to start developing your own emulator. Below are described some of the major steps you will have to follow in order to reach this goal:
- Define the scope of the API you want to have a Xenomai skin for.
- Start crafting the task create/resume/suspend/delete services first and make them work rock-solid. Using the simulator will help you improve the robustness of your implementation.
- Add the semaphores, or the events, i.e. any kind of feature that exercises basic inter-task synchronization. Write it, test it over the simulator.
- Finalize the task support over Xenosim.
- Add an inter-task communication feature in your skin; write it, validate it over the simulator.
- At that point, calm down a bit, because you will likely be hit by the OMSCBD syndrom. You really need to be very careful with this: when you hear yourself saying "ok, I want to finish One More System Call Before Diner", then you've likely already coded 70 services within a day, but you feel you need more :) It's addictive, and if you don't take care, you will end up roaming in your neighborhood with an insane smile on your face.
When you feel your Xenomai skin is complete and stable enough, move it to kernel or hard VM space. It should work exactely as it did under the virtual RT machine.
In any case: code the initial version of your skin using the simulator, do not go blindly for kernel space. This simulator runs the actual Xenomai nucleus you will be able to run later in the "real" real-time space when the dust has settled. Developing a RTOS in bare kernel space when a reliable simulation framework is available is like wearing a knight's armor to go swimming: all you can do is bravely...sink!
Tools
Embedded Linux distribution integrating Xenomai
ELDK: The Embedded Linux Development Kit (ELDK) 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.
Support
Community support
TBC: explain the perimeter of the support i.e. that the best support a user can take advantage of is to be on the latest stable release. Reference to Gilles' email: "Anyway, in case you wonder why we focus on mainline support only: because maintaining support for patched kernel is a major PITA and becomes obsolete fast. So, our current active development branch is Linux mainline, exclusively. We make an exception for the AT91 patch, because it is an "antichambre" of the mainline support for AT91, not a fork, and even then, we try hard to make an adeos I-pipe patch which applies with or without the AT91 patch."
Mailing lists
Two mailing lists are available in order to get some help on Xenomai. If you do not find answers to your questions in the documentation which ships with Xenomai sources or in the FAQ, please use these mailing lists, DO NOT leave questions on the wiki. In case you do not know which mailing list to send your question to, please use the xenomai-help mailing list:
- Xenomai-help The xenomai-help mailing list handles discussions about configuration, compilation or installation of Xenomai, as well as common usage of its features and interfaces.
- Xenomai-core The xenomai-core mailing list handles general discussions and development issues about the Xenomai system; in other words, it is the place where all aspects of the Xenomai project's life are debated. Bug reports and patches should be sent here too.
How to post on the mailing-list
In order to get help from the community, you have to make sure you provide relevant information in your post before posting. A typical request should contain:
- A detailed description of your hardware: architecture, processor, board, peripherals...
- A description of the toolchain (gcc version, binutils).
- Eventually the embedded distribution you are using for your project.
- The output of the xeno-info command.
- All relevant logs helping to understand the problem you encounter.
- Description of the use case causing the problem.
- Ideally a piece of code allowing to reproduce the problem.
Commercial support
TBD...
Other readings
The following books or articles are interesting references if you want to improve your knowledge regarding Xenomai technology:
