Running applications with Xenomai 3.x
=====================================

Running a Xenomai 3 application
-------------------------------

For _Cobalt_, you will need the real-time core built into the target
Linux kernel as described in link:installing-xenomai-3-x[this
document].

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.

Any Xenomai-based application recognizes a set of standard options
that may be passed on the command line, described in
link:application-setup-and-init#Standard_Xenomai_command_line_options[this document].

In addition, the *Alchemy*, *pSOS (TM)* and *VxWorks (TM)* APIs running
over the Xenomai core can define the clock resolution to be used,
given as a count of nano-seconds, i.e. HZ=(1000000000 / ns), by the
+--{alchemy/psos/vxworks}-clock-resolution=<ns>+ option.

If your application combines multiple APIs, you may pass several
clock-resolution switches to set them all.

The default value depends on the API being considered. For instance,
the VxWorks (TM) and pSOS (TM) emulators default to millisecond clock
rates. The Alchemy API is tickless by default,
i.e. +--alchemy-clock-resolution=1+.

[CAUTION]
Specifying a resolution greater than 1 nanosecond requires the low
resolution clock support to be available from the Xenomai libraries
(see the +--enable-lores-clock+
link:installing-xenomai-3-x#Generic_configuration_options_both_cores[configuration
switch]).

Valgrind support
----------------

Running Xenomai applications over _Valgrind_ is currently available to
the _Mercury_ core only.

When the Valgrind API is available to the application process, the
configuration symbol CONFIG_XENO_VALGRIND_API is defined at build
time, and may be tested for existence by the application code. See the
tool documentation at
http://valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.clientreq/[this address].

The Xenomai autoconf script will detect the Valgrind core header on
the build system automatically, and define this symbol accordingly
(i.e. /usr/include/valgrind/valgrind.h).

[NOTE]
You may need to install the Valgrind development package on your build
system to provide for the core header files. For instance, such
package is called _valgrind-devel_ on Fedora.

Available real-time APIs
------------------------

[horizontal]
*Alchemy*::
		This is a re-implementation from scratch of Xenomai's
		2.x _native_ API, fully rebased on the new RTOS
		abstraction interface.

*pSOS*::
		http://www.windriver.com[pSOS (TM)] is a registered
		trademark of Wind River Systems, Inc.

*VxWorks*::
		http://www.windriver.com[VxWorks (TM)] is a registered
		trademark of Wind River Systems, Inc.