Installing Xenomai 3.x
|
======================
|
|
Introduction
|
------------
|
|
Xenomai 3 is the new architecture of the Xenomai real-time framework,
|
which can run seamlessly side-by-side Linux as a co-kernel system, or
|
natively over mainline Linux kernels. In the latter case, the
|
mainline kernel can be supplemented by the
|
https://www.kernel.org/pub/linux/kernel/projects/rt/[PREEMPT-RT patch]
|
to meet stricter response time requirements than standard kernel
|
preemption would bring.
|
|
One of the two available real-time cores is selected at build
|
time. The dual kernel core is codenamed _Cobalt_, the native Linux
|
implementation is called _Mercury_.
|
|
[NOTE]
|
If you are looking for detailed information about installing a legacy
|
Xenomai 2.x release, please refer to link:installing-xenomai-2.x[this
|
document] instead. Please note that Xenomai 2.x is discontinued and
|
not maintained anymore.
|
|
Installation steps
|
------------------
|
|
Xenomai follows a split source model, decoupling the kernel space
|
support from the user-space libraries.
|
|
To this end, kernel and user-space Xenomai components are respectively
|
available under the `kernel/` and `lib/` sub-trees. Other top-level
|
directories, such as `scripts/`, `testsuite/` and `utils/`, provide
|
additional scripts and programs to be used on either the build host,
|
or the runtime target.
|
|
The `kernel/` sub-tree which implements the in-kernel support code is
|
seen as a built-in extension of the Linux kernel. Therefore, the
|
standard Linux kernel configuration process should be used to define
|
the various settings for the Xenomai kernel components. All of the
|
kernel code Xenomai currently introduces implements the _Cobalt_ core
|
(i.e. dual kernel configuration). As of today, the _Mercury_ core
|
needs no Xenomai-specific code in kernel space.
|
|
The `lib/` sub-tree contains the various user-space libraries exported
|
by the Xenomai framework to the applications. This tree is built
|
separately from the kernel support. Libraries are built in order to
|
support the selected core, either _Cobalt_ or _Mercury_.
|
|
[[cobalt-core-install]]
|
Installing the _Cobalt_ core
|
----------------------------
|
Preparing the _Cobalt_ kernel
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
_Xenomai/cobalt_ provides a real-time extension kernel 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:
|
|
------------------------------------------------------------------------------
|
$ scripts/prepare-kernel.sh [--linux=<linux-srctree>]
|
[--ipipe=<ipipe-patch>] [--arch=<target-arch>]
|
------------------------------------------------------------------------------
|
|
`--linux`:: specifies the path of the target kernel source tree. Such
|
kernel tree may be already configured or not, indifferently. This
|
path defaults to $PWD.
|
|
`--ipipe`:: specifies the path of the interrupt pipeline (aka I-pipe)
|
patch to apply against the kernel tree. Suitable patches are
|
available from the project's link:/downloads/ipipe/[download
|
area]. This parameter can be omitted if the I-pipe has already
|
been patched in, or the script shall suggest an appropriate
|
one. The script will detect whether the interrupt pipeline code is
|
already present into the kernel tree, and skip this operation if
|
so.
|
|
`--arch`:: tells the script about the target architecture. If
|
unspecified, the build host architecture suggested as a reasonable
|
default.
|
|
For instance, the following command would prepare the Linux tree
|
located at `/home/me/linux-3.10-ipipe` in order to patch the Xenomai
|
support in:
|
|
------------------------------------------------------------------------------
|
$ cd xenomai-3
|
$ scripts/prepare-kernel.sh --linux=/home/me/linux-3.10
|
------------------------------------------------------------------------------
|
|
Note: The script will infer the location of the Xenomai kernel code
|
from its own location within the Xenomai source tree. For instance, if
|
`/home/me/xenomai-3/scripts/prepare-kernel.sh` is executing, then
|
the Xenomai kernel code available from
|
`/home/me/xenomai-3/kernel/cobalt` will be patched in the target
|
Linux kernel.
|
|
|
Configuring and compiling the _Cobalt_ kernel
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Once prepared, the target kernel can be configured as usual. All
|
Xenomai configuration options are available from the "Xenomai"
|
toplevel Kconfig menu.
|
|
There are several important kernel configuration options, documented
|
in the link:troubleshooting-a-dual-kernel-configuration#kconf[TROUBLESHOOTING]
|
guide.
|
|
Once configured, the kernel can be compiled as usual.
|
|
If you want several different configs/builds at hand, you may reuse
|
the same source by adding `O=../build-<target>` to each make
|
invocation.
|
|
In order to cross-compile the Linux kernel, pass an ARCH and
|
CROSS_COMPILE variable on make command line. See sections
|
<<cobalt-core-arm,"Building a _Cobalt/arm_ kernel">>,
|
<<cobalt-core-powerpc,"Building a _Cobalt/powerpc_ kernel">>,
|
<<cobalt-core-x86,"Building a _Cobalt/x86_ kernel">>,
|
for examples.
|
|
[[cobalt-kernel-parameters]]
|
_Cobalt_ kernel parameters
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
The Cobalt kernel accepts the following set of parameters, which
|
should be passed on the kernel command line by the boot loader.
|
|
[options="header",grid="cols",frame="topbot",cols="2,3,1"]
|
|============================================================================
|
^|NAME ^|DESCRIPTION ^|DEFAULT
|
|
|xenomai.allowed_group=<gid> | Enable non-root access to Xenomai
|
services from user-space. <gid> is the ID of the Linux user group
|
whose members should be allowed such access by the Cobalt core. | None
|
|
|xenomai.sysheap_size=<kbytes> | Set the size of the memory heap used
|
internally by the Cobalt core to allocate runtime objects. This value
|
is expressed in kilo-bytes. | 256
|
|
|xenomai.state=<state> | Set the initial state of the Cobalt core at
|
boot up, which may be _enabled_, _stopped_ or _disabled_. See the
|
documentation about the
|
link:../documentation/xenomai-3/html/man1/corectl/index.html[corectl(1)]
|
utility for a description of these states. | enabled
|
|
|xenomai.smi=<state> | *x86-specific*: Set the state of the SMI
|
workaround. The possible values are _disabled_, _detect_ and
|
_enabled_. See the discussion about link:dealing-with-x86-SMI[SMIs]
|
for a description of these states.| detect
|
|
|xenomai.smi_mask=<source-mask> | *x86-specific*: Set of bits to mask
|
in the SMI control register. | 1 (=global disable)
|
|
|============================================================================
|
|
[[cobalt-build-examples]]
|
Examples of building the _Cobalt_ kernel
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
The examples in following sections use the following conventions:
|
|
`$linux_tree`:: path to the target kernel sources
|
`$xenomai_root`:: path to the Xenomai sources
|
|
|
[[cobalt-core-x86]]
|
Building a _Cobalt/x86_ kernel (32/64bit)
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
Building _Xenomai/cobalt_ for x86 is almost the same for 32bit and 64bit
|
platforms. You should note, however, that it is not possible to run
|
Xenomai libraries compiled for x86_32 on a kernel compiled for x86_64,
|
and conversely.
|
|
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:
|
|
------------------------------------------------------------------------------
|
$ cd $linux_tree
|
$ $xenomai_root/scripts/prepare-kernel.sh --arch=x86 \
|
--ipipe=ipipe-core-X.Y.Z-x86-NN.patch
|
$ make [ARCH=i386] xconfig/gconfig/menuconfig
|
------------------------------------------------------------------------------
|
...configure the kernel (see also the recommended settings
|
link:configuring-for-x86-based-dual-kernels[here]).
|
|
Enable Xenomai options, then build with:
|
------------------------------------------------------------------------------
|
$ make [ARCH=i386] bzImage modules
|
------------------------------------------------------------------------------
|
|
Now, let's say that you really want to build Xenomai for a
|
Pentium-based x86 32bit platform, using the native host toolchain; the
|
typical steps would be as follows:
|
|
------------------------------------------------------------------------------
|
$ cd $linux_tree
|
$ $xenomai_root/scripts/prepare-kernel.sh --arch=i386 \
|
--ipipe=ipipe-core-X.Y.Z-x86-NN.patch
|
$ make xconfig/gconfig/menuconfig
|
------------------------------------------------------------------------------
|
...configure the kernel (see also the recommended settings
|
link:configuring-for-x86-based-dual-kernels[here]).
|
|
Enable Xenomai options, then build with:
|
------------------------------------------------------------------------------
|
$ make bzImage modules
|
------------------------------------------------------------------------------
|
|
Similarly, for a 64bit platform, you would use:
|
|
------------------------------------------------------------------------------
|
$ cd $linux_tree
|
$ $xenomai_root/scripts/prepare-kernel.sh --arch=x86_64 \
|
--ipipe=ipipe-core-X.Y.Z-x86-NN.patch
|
$ make xconfig/gconfig/menuconfig
|
------------------------------------------------------------------------------
|
...configure the kernel (see also the recommended settings
|
link:configuring-for-x86-based-dual-kernels[here]).
|
|
Enable Xenomai options, then build with:
|
------------------------------------------------------------------------------
|
$ make bzImage modules
|
------------------------------------------------------------------------------
|
|
The remaining examples illustrate how to cross-compile a
|
_Cobalt_-enabled kernel for various architectures. Of course, you would
|
have to install the proper cross-compilation toolchain for the target
|
system first.
|
|
[[cobalt-core-powerpc]]
|
Building a _Cobalt/powerpc_ kernel
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
A typical cross-compilation setup, in order to build Xenomai for a
|
ppc-6xx architecture running a 3.10.32 kernel. We use the DENX ELDK
|
cross-compiler:
|
|
------------------------------------------------------------------------------
|
$ cd $linux_tree
|
$ $xenomai_root/scripts/prepare-kernel.sh --arch=powerpc \
|
--ipipe=ipipe-core-3.10.32-powerpc-1.patch
|
$ make ARCH=powerpc CROSS_COMPILE=ppc_6xx- xconfig/gconfig/menuconfig
|
------------------------------------------------------------------------------
|
...select the kernel and Xenomai options, save the configuration
|
------------------------------------------------------------------------------
|
$ make ARCH=powerpc CROSS_COMPILE=powerpc-linux- uImage modules
|
------------------------------------------------------------------------------
|
...manually install the kernel image and modules to the proper location
|
|
[[cobalt-core-arm]]
|
Building _Cobalt/arm_ kernel
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
Using codesourcery toolchain named `arm-none-linux-gnueabi-gcc` and
|
compiling for a CSB637 board (AT91RM9200 based), a typical compilation
|
will look like:
|
|
------------------------------------------------------------------------------
|
$ cd $linux_tree
|
$ $xenomai_root/scripts/prepare-kernel.sh --arch=arm \
|
--ipipe=ipipe-core-X.Y.Z-x86-NN.patch
|
$ mkdir -p $build_root/linux
|
$ make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- O=$build_root/linux \
|
csb637_defconfig
|
$ make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- O=$build_root/linux \
|
bzImage modules
|
------------------------------------------------------------------------------
|
...manually install the kernel image, system map and modules to the proper location
|
|
|
[[mercury-core-install]]
|
Installing the _Mercury_ core
|
-----------------------------
|
|
For _Mercury_, you need no Xenomai-specific kernel support so far,
|
beyond what your host Linux kernel already provides. Your kernel
|
should at least provide high resolution timer support
|
(`CONFIG_HIGH_RES_TIMERS`), and likely complete preemption
|
(_PREEMPT_RT_) if your application requires short and bounded
|
latencies.
|
|
Kernels with no real-time support can be used too, likely for basic
|
debugging tasks, and/or running applications which do not have strict
|
response time requirements.
|
|
Therefore, unlike with _Cobalt_, there is no additional steps for
|
preparing and/or configuring the kernel for _Mercury_.
|
|
[[library-install]]
|
Installing the Xenomai libraries and tools
|
------------------------------------------
|
|
Prerequisites
|
~~~~~~~~~~~~~
|
|
Generic requirements (both cores)
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
- GCC must have support for legacy atomic builtins (__sync form).
|
|
- GCC should have a (sane/working) support for TLS preferably,
|
although this is not mandatory if building with `--disable-tls`.
|
|
- If you plan to enable the user-space registry support
|
(i.e. +--enable-registry+), then CONFIG_FUSE_FS must be enabled in
|
the target kernel running the real-time applications. In addition,
|
the FUSE development libraries must be available from the toolchain.
|
|
- If you plan to build from the sources available from the Xenomai GIT
|
tree (git.xenomai.org), the autoconf (>= 2.62), automake and libtool
|
packages must be available on your build system. This is not
|
required when building from a source tree extracted from a
|
link:/downloads/xenomai/[release tarball].
|
|
_Cobalt_-specific requirements
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
- The kernel version must be 3.10 or better.
|
|
- An interrupt pipeline (I-pipe) patch must be available for your
|
target kernel. You can find the official patches issued by the
|
Xenomai project link:/downloads/ipipe/[there].
|
Only patches from the *ipipe-core* series are appropriate, legacy
|
patches from the *adeos-ipipe* series are not.
|
|
- A timestamp counter (TSC) is required from running on a x86_32
|
hardware. Unlike with Xenomai 2.x, TSC-emulation using a PIT
|
register is not available.
|
|
_Mercury_-specific requirement
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
- There is no particular requirement for Mercury setups, although
|
using a NPTL-based glibc or uClibc is recommended.
|
|
Configuring
|
~~~~~~~~~~~
|
|
If building the source obtained from the Xenomai GIT tree
|
(git.xenomai.org), the `configure` script and Makefiles must be
|
generated in the Xenomai source tree. The recommended way is to run
|
the automatic reconfiguration script shipped, from the top of the
|
source tree:
|
|
---------------------
|
$ ./scripts/bootstrap
|
---------------------
|
|
If building from a link:/downloads/xenomai/[release tarball], a set of
|
autoconf-generated file will be readily available from the extracted
|
source tree, and therefore reconfiguring will not be required.
|
|
When run, the generated `configure` script prepares for building the
|
libraries and programs, for both the _Cobalt_ and _Mercury_ cores. The
|
core-specific code which may be needed internally is automatically and
|
transparently selected at compilation-time by the build process.
|
|
The options listed below can be passed to this script.
|
|
Generic configuration options (both cores)
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
[horizontal]
|
*--with=core=<type>*::
|
|
Indicates which real-time core you want to build the support
|
libraries for, namely _cobalt_ or _mercury_. This option
|
defaults to _cobalt_.
|
|
*--prefix=<dir>*::
|
|
Specifies the root installation path for libraries, include
|
files, scripts and executables. Running `$ make install`
|
installs these files to `$DESTDIR/<dir>`. This directory
|
defaults to /usr/xenomai.
|
|
*--enable-debug[=partial]*::
|
|
This switch controls the debug level. Three levels are
|
available, with varying overhead:
|
|
- _symbols_ enables debug symbols to be compiled in the
|
libraries and executables, still turning on the optimizer
|
(-O2). This option has no overhead, it is useful to get
|
meaningful backtraces using gdb while running the application
|
at nominal speed.
|
|
- _partial_ includes _symbols_, and also turns on internal
|
consistency checks within the Xenomai code (mostly present in
|
the Copperplate layer). The `CONFIG_XENO_DEBUG` macro is
|
defined, for both the Xenomai libraries and the applications
|
getting their C compilation flags from the `xeno-config`
|
script (i.e. `xeno-config --cflags`). The partial debug mode
|
implicitly turns on `--enable-assert`. A measurable overhead
|
is introduced by this level. This is the default level when
|
`--enable-debug` is mentioned with no level specification.
|
|
- _full_ includes _partial_ settings, but the optimizer is
|
disabled (-O0), and even more consistency checks may be
|
performed. In addition to `__XENO_DEBUG__`, the macro
|
`CONFIG_XENO_DEBUG_FULL` is defined. This level introduces the
|
most overhead, which may triple the worst-case latency, or
|
even more.
|
|
[normal]
|
Over the _Mercury_ core, enabling _partial_ or _full_ debug
|
modes also causes the standard malloc interface to be used
|
internally instead of a fast real-time allocator (TLSF). This
|
allows debugging memory-related issues with the help of
|
_Valgrind_ or other dynamic memory analysers.
|
|
*--disable-debug*::
|
|
Fully turns off all consistency checks and assertions, turns
|
on the optimizer and disables debug symbol generation.
|
|
*--enable-assert*::
|
|
A number of debug assertion statements are present into the
|
Xenomai libraries, checking the internal consistency of the
|
runtime system dynamically (see _man assert(3)_). Passing
|
`--disable-assert` to the _configure_ script disables built-in
|
assertions unconditionally. By default, assertions are enabled
|
in partial or full debug modes, disabled otherwise.
|
|
*--enable-pshared*::
|
|
Enable shared multi-processing. When enabled, this option
|
allows multiple processes to share real-time objects
|
(e.g. tasks, semaphores).
|
|
*--enable-registry[=/registry-root-path]*::
|
|
Xenomai APIs can export their internal state through a
|
pseudo-filesystem, which files may be read to obtain
|
information about the existing real-time objects, such as
|
tasks, semaphores, message queues and so on. This feature is
|
supported by http://fuse.sourceforge.net/[FUSE], which must be
|
available on the target system. Building the Xenomai libraries
|
with the registry support requires the FUSE development
|
libraries to available from the toolchain. In addition,
|
CONFIG_FUSE_FS must be enabled in the target kernel.
|
|
[normal]
|
When this option is enabled, the system creates a file hierachy at
|
`<user>/<session>/<pid>` under the registry root path, where you
|
can access the internal state of the active real-time objects. The
|
session label is obtained from the --session runtime switch. If no
|
session name is specified, `anon@<pid>` will be used. E.g. looking at
|
the properties of a VxWorks task could be done as follows:
|
|
If not specified in the configuration switch, the registry root path
|
will be +/var/run/xenomai+.
|
|
--------------------------------------------------------------------
|
$ cat /var/run/xenomai/root/anon@12656/12656/vxworks/tasks/windTask
|
name = windTask
|
errno = 0
|
status = ready
|
priority = 70
|
lock_depth = 0
|
--------------------------------------------------------------------
|
|
[normal]
|
You may override the default root of the registry hierarchy
|
either statically at build time by passing the desired root
|
path to the --enable-registry configuration switch, or
|
dynamically by using the `--registry-root` runtime option
|
passed to the application.
|
|
[NOTE]
|
When running over _Xenomai/cobalt_, the `/proc/xenomai` interface is
|
also available for inspecting the core system state.
|
|
*--enable-lores-clock*::
|
|
Enables support for low resolution clocks. By default,
|
libraries are built with no support for tick-based timing. If
|
you need such support (e.g. for pSOS (TM) or VxWorks (TM)
|
APIs), then you can turn it on using this option.
|
|
[NOTE]
|
The POSIX API does not support tick-based timing. Alchemy may use it
|
optionally.
|
|
*--enable-clock-monotonic-raw*::
|
|
The Xenomai libraries requires a monotonic clock to be
|
available from the underlying POSIX interface. When
|
`CLOCK_MONOTONIC_RAW` is available on your system, you may
|
want to pass this switch, otherwise `CLOCK_MONOTONIC` will be
|
used by default.
|
|
[NOTE]
|
The _Cobalt_ core implements `CLOCK_MONOTONIC_RAW`, so this switch is
|
turned on by default when building with `--with-core=cobalt`. On the
|
contrary, this option is turned off by default when building for the
|
_Mercury_ core, since we don't know in advance whether this feature
|
does exist on the target kernel.
|
|
*--enable-tls*::
|
|
Xenomai can use GCC's thread local storage extension (TLS) to
|
speed up the retrieval of the per-thread information it uses
|
internally. This switch enables TLS, use the converse
|
`--disable-tls` to prevent this.
|
|
[normal]
|
Due to GCC bugs regarding this feature with some
|
release,architecture combinations, whether TLS is turned on by
|
default is a per-architecture decision. Currently, this
|
feature is enabled for x86 and powerpc by default, other
|
architectures will require `--enable-tls` to be passed to the
|
_configure_ script explicitly.
|
|
[normal]
|
Unless `--enable-dlopen-libs` is present, the _initial-exec_
|
TLS model is selected.
|
|
[normal]
|
When TLS is disabled, POSIX's thread-specific data management
|
services are used internally (i.e. pthread_set/getspecific()).
|
|
*--enable-dlopen-libs*::
|
|
This switch allows programs to load Xenomai-based libraries
|
dynamically, using the `dlopen(3)` routine. Enabling dynamic
|
loading introduces some overhead in TLS accesses when enabled
|
(see `--enable-tls`), which might be noticeable depending on
|
the architecture.
|
|
[normal]
|
To support dynamic loading when `--enable-tls` is turned on,
|
the _global-dynamic_ TLS model is automatically selected.
|
|
[normal]
|
Dynamic loading of Xenomai-based libraries is disabled by
|
default.
|
|
*--enable-async-cancel*::
|
|
Enables fully asynchronous cancellation of Xenomai threads
|
created by the real-time APIs, making provision to protect the
|
Xenomai implementation code accordingly.
|
[normal]
|
When disabled, Xenomai assumes that threads may exit due to
|
cancellation requests only when they reach cancellation points
|
(like system calls). Asynchronous cancellation is disabled
|
by default.
|
|
[CAUTION]
|
Fully asynchronous cancellation can easily lead to resource leakage,
|
silent corruption, safety issues and all sorts of rampant bugs. The
|
only reason to turn this feature on would be aimed at cancelling
|
threads which run significantly long, syscall-less busy loops with no
|
explicit exit condition, which should probably be revisited anyway.
|
|
*--enable-smp*::
|
|
Turns on SMP support for Xenomai libraries.
|
|
[CAUTION]
|
SMP support must be enabled in Xenomai libraries when the
|
client applications are running over a SMP-capable kernel.
|
|
*--disable-sanity*::
|
|
Turns off the sanity checks performed at application startup
|
by the Xenomai libraries. This option sets a default, which
|
can later be overriden using the --[no-]sanity options passed
|
to a Copperplate-based Xenomai application. Sanity checks are
|
enabled by default when configuring.
|
|
*--enable-fortify*::
|
|
Enables `_FORTIFY_SOURCE` when building the Xenomai code
|
unless --enable-debug=full is also given on the command line,
|
in which case --enable-fortify is silently ignored.
|
|
*--disable-valgrind-client*::
|
|
Turns off the Valgrind client support, forcing
|
`CONFIG_XENO_VALGRIND_API` off in the Xenomai configuration
|
header.
|
|
*--enable-doc-build*::
|
|
Causes the inline Xenomai documentation based on the
|
http://doxygen.org[Doxygen markup language] to be produced as
|
PDF and HTML documents. Additional documentation like manpages
|
based on the http://asciidoc.org/[Asciidoc markup language] is
|
produced too.
|
|
_Cobalt_-specific configuration options
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
[options="header",grid="cols",frame="topbot",cols="m,2*d"]
|
|============================================================================
|
^|NAME ^|DESCRIPTION ^|DEFAULT
|
|--enable-x86-vsyscall |Use the x86/vsyscall interface
|
for issuing syscalls. If disabled,
|
the legacy 0x80 vector will be used.
|
Turning on this option requires NPTL. |enabled
|
|
|--enable-arm-tsc |Enable ARM TSC emulation.
|
footnote:[In the unusual
|
situation where Xenomai
|
does not support the kuser generic
|
emulation for the target SOC, use
|
this option to specify another tsc
|
emulation method.
|
See `--help` for a list of valid
|
values.] |kuser
|
|
|--enable-arm-quirks |Enable quirks for specific ARM
|
SOCs Currently sa1100 and
|
xscale3 are supported. |disabled
|
|============================================================================
|
|
_Mercury_-specific configuration options
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
[options="header",grid="cols",frame="topbot",cols="m,2*d"]
|
|============================================================================
|
^|NAME ^|DESCRIPTION ^|DEFAULT
|
|--enable-condvar-workaround | Enable workaround for broken priority
|
inheritance with condition variables in glibc. This option
|
adds some overhead to RTOS API emulators. |disabled
|
|============================================================================
|
|
footnoteref:[disable,Each option enabled by default can be forcibly
|
disabled by passing `--disable-<option>` to the _configure_ script]
|
|
Cross-compilation
|
~~~~~~~~~~~~~~~~~
|
|
In order to cross-compile the Xenomai libraries and programs, 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 PowerPC architecture may be named
|
`powerpc-linux-gcc`.
|
|
When passing `--host=powerpc-linux` to configure, it will
|
automatically use `powerpc-linux-` 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.
|
|
The easiest way to build a GNU cross-compiler might involve using
|
crosstool-ng, available http://crosstool-ng.org/[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 required on the target
|
system. See http://www.denx.de/wiki/DULG/ELDK[here] for further
|
details.
|
|
Some other pre-built toolchains:
|
|
- Mentor Sourcery CodeBench Lite Edition, available
|
http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/[here];
|
- Linaro toolchain (for the ARM architecture), available
|
https://launchpad.net/linaro-toolchain-binaries[here].
|
|
|
[[library-install-examples]]
|
Examples of building the Xenomai libraries and tools
|
----------------------------------------------------
|
|
The examples in following sections use the following conventions:
|
|
`$xenomai_root`:: path to the Xenomai sources
|
`$build_root`:: path to a clean build directory
|
`$staging_dir`:: path to a directory that will hold the installed file
|
temporarily before they are moved to their final location; when used
|
in a cross-compilation setup, it is usually a NFS mount point from
|
the target's root directory to the local build host, as a
|
consequence of which running `make{nbsp}DESTDIR=$staging_dir{nbsp}install` on
|
the host immediately updates the target system with the installed
|
programs and libraries.
|
|
CAUTION: In the examples below, make sure to add `--enable-smp` to the
|
_configure_ script options if building for a SMP-enabled kernel.
|
|
Building the x86 libraries (32/64bit)
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Assuming that you want to build the _Mercury_ libraries natively for a
|
x86_64/SMP system, enabling shared multi-processing support. You would
|
typically run:
|
|
------------------------------------------------------------------------------
|
$ mkdir $build_root && cd $build_root
|
$ $xenomai_root/configure --with-core=mercury --enable-smp --enable-pshared
|
$ make install
|
------------------------------------------------------------------------------
|
|
Conversely, cross-building the _Cobalt_ libraries from x86_64 with the
|
same feature set, for running on x86_32 could be:
|
|
------------------------------------------------------------------------------
|
$ mkdir $build_root && cd $build_root
|
$ $xenomai_root/configure --with-core=cobalt --enable-smp --enable-pshared \
|
--host=i686-linux CFLAGS="-m32 -O2" LDFLAGS="-m32"
|
$ make install
|
------------------------------------------------------------------------------
|
|
After installing the build tree (i.e. using "make install"), the
|
installation root should be populated with the librairies, programs
|
and header files you can use to build Xenomai-based real-time
|
applications. This directory path defaults to `/usr/xenomai`.
|
|
The remaining examples illustrate how to cross-compile Xenomai for
|
various architectures. Of course, you would have to install the proper
|
cross-compilation toolchain for the target system first.
|
|
Building the PPC32 libraries
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
A typical cross-compilation setup, in order to build the _Cobalt_
|
libraries for a ppc-6xx architecture. In that example, we want the
|
debug symbols to be generated for the executable, with no runtime
|
overhead though. We use the DENX ELDK cross-compiler:
|
|
------------------------------------------------------------------------------
|
$ cd $build_root
|
$ $xenomai_root/configure --host=powerpc-linux --with-core=cobalt \
|
--enable-debug=symbols
|
$ make DESTDIR=$staging_dir install
|
------------------------------------------------------------------------------
|
|
Building the ARM libraries
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Using codesourcery toolchain named `arm-none-linux-gnueabi-gcc` and
|
compiling for a CSB637 board (AT91RM9200 based), a typical cross-compilation
|
from a x86_32 desktop would look like:
|
|
------------------------------------------------------------------------------
|
$ mkdir $build_root/xenomai && cd $build_root/xenomai
|
$ $xenomai_root/configure CFLAGS="-march=armv4t" LDFLAGS="-march=armv4t" \
|
--build=i686-pc-linux-gnu --host=arm-none-linux-gnueabi- --with-core=cobalt
|
$ make DESTDIR=$staging_dir install
|
------------------------------------------------------------------------------
|
|
IMPORTANT: Unlike previous releases, Xenomai no longer passes any arm
|
architecture specific flags, or FPU flags to gcc, so, users are
|
expected to pass them using the CFLAGS and LDFLAGS variables as
|
demonstrated above, where the AT91RM9200 is based on the ARM920T core,
|
implementing the `armv4` architecture. The following table summarizes
|
the CFLAGS and options which were automatically passed in previous
|
revisions and which now need to be explicitely passed to configure,
|
for the supported SOCs:
|
|
.ARM configure options and compilation flags
|
[options="header",frame="topbot",grid="cols",cols="2*d,m"]
|
|======================================================================
|
^|SOC ^| CFLAGS ^| configure options
|
|at91rm9200 | `-march=armv4t -msoft-float` |
|
|at91sam9x | `-march=armv5 -msoft-float` |
|
|imx1 | `-march=armv4t -msoft-float` |
|
|imx21 | `-march=armv5 -msoft-float` |
|
|imx31 | `-march=armv6 -mfpu=vfp` |
|
|imx51/imx53 | `-march=armv7-a -mfpu=vfp3`
|
footnoteref:[armv7,Depending on the
|
gcc versions the flag for armv7
|
may be `-march=armv7-a` or
|
`-march=armv7a`]|
|
|imx6q | `-march=armv7-a -mfpu=vfp3` footnoteref:[armv7] | --enable-smp
|
|ixp4xx | `-march=armv5 -msoft-float` | `--enable-arm-tsc=ixp4xx`
|
|omap3 | `-march=armv7-a -mfpu=vfp3` footnoteref:[armv7] |
|
|omap4 | `-march=armv7-a -mfpu=vfp3` footnoteref:[armv7] | --enable-smp
|
|orion | `-march=armv5 -mfpu=vfp` |
|
|pxa | `-march=armv5 -msoft-float` |
|
|pxa3xx | `-march=armv5 -msoft-float` | --enable-arm-quirks=xscale3
|
|s3c24xx | `-march=armv4t -msoft-float` |
|
|sa1100 | `-march=armv4t -msoft-float` | --enable-arm-quirks=sa1100
|
|======================================================================
|
|
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.
|
|
|
Testing the installation
|
------------------------
|
|
Booting the _Cobalt_ kernel
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
In order to test the Xenomai installation over _Cobalt_, you should
|
first try to boot the patched kernel. Check the kernel boot log for
|
messages like these:
|
|
------------------------------------------------------------------------------
|
$ dmesg | grep -i xenomai
|
I-pipe: head domain Xenomai registered.
|
[Xenomai] Cobalt vX.Y.Z enabled
|
------------------------------------------------------------------------------
|
|
|
If the kernel fails booting, or the log messages indicates an error
|
status instead, see the
|
link:troubleshooting-a-dual-kernel-configuration#Kernel_log_displays_Xenomai_or_I-pipe_error_messages[TROUBLESHOOTING]
|
guide.
|
|
|
Testing the real-time system (both cores)
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
First, run the latency test:
|
|
------------------------------------------------------------------------------
|
$ /usr/xenomai/bin/latency
|
------------------------------------------------------------------------------
|
|
The latency test should display a message every second with minimum,
|
maximum and average latency values. If this test displays an error
|
message, hangs, or displays unexpected values, see the
|
link:troubleshooting-a-dual-kernel-configuration#the_latency_test_shows_high_latencies[TROUBLESHOOTING]
|
guide.
|
|
If the latency test succeeds, you should try next to run the
|
`xeno-test` test in order to assess the worst-case latency of your
|
system. Try:
|
|
------------------------------------------------------------------------------
|
$ xeno-test --help
|
------------------------------------------------------------------------------
|
|
Calibrating the _Cobalt_ core timer
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
The accuracy of the Cobalt timing services depends on proper
|
calibration of its core timer. Sound factory-default calibration
|
values are defined for each platform Xenomai supports, but it is
|
recommended to calibrate the core timer specifically for the target
|
system.
|
|
See the documentation about the
|
link:../documentation/xenomai-3/html/man1/autotune/index.html[autotune(1)]
|
utility.
|
|
Building and running Xenomai 3 applications
|
-------------------------------------------
|
|
Once the latency test behaves as expected on your target system, it is
|
deemed ready to run real-time applications.
|
|
You may want to have a look at
|
link:building-applications-with-xenomai-3.x/[this
|
document] for details about the application build process.
|
|
In addition, you may refer to
|
link:running-applications-with-xenomai-3.x/[this document] to learn
|
about the command line options available with Xenomai 3 applications.
|
|
Migrating applications to Xenomai 3
|
-----------------------------------
|
|
If you plan to port an existing application based on Xenomai 2.x to
|
Xenomai 3.x, you should have a look at
|
link:migrating-from-xenomai-2.x-to-3.x/[this migration guide].
|
