This is Xenomai 3.x, the upcoming architecture of the Xenomai RTOS
emulation system, which can run seamlessly as a dual kernel (i.e. like
Xenomai 2.x, I-pipe based), or over mainline Linux kernels (likely
PREEMPT-RT enabled though).

This new architecture therefore exhibits two real-time cores, selected
at build time. The dual kernel core inherited from the Xenomai 2.x
architecture is nicknamed "Cobalt". The native linux core inherited
from the former Xenomai/SOLO work is called "Mercury".

This magic works with the introduction of the "Copperplate" interface,
which mediates between the real-time API/emulator your application
uses, and the underlying real-time core. This way, applications are
able to run in either environments without visible change.

This is experimental, work in progress, very much in flux code. The
basic design won't change anymore though. Not all features we want to
see there are available yet.

Performance-wise, we have no figure yet. However, this new design is
known to significantly reduce the number of user/kernel transitions
due to system calls on average compared to the 2.x architecture, which
can't be bad.

Prerequisites
=============

-- To run over the Cobalt core

All like in the old days, as one used to bring up a Xenomai 2.x
system, i.e:

1. An interrupt pipeline patch which fits your hardware. Recent ones
are readily available from the Xenomai source tree (see
kernel/cobalt/nucleus/arch/*/patches). All existing patches can be
found at http://download.gna.org/adeos/patches/

2. A working port of the Cobalt core to the target architecture. We
intend to support the same set as available with Xenomai
2.6.x.

-- To run over the Mercury core

1. A recent glibc featuring the NPTL thread library, with priority
inheritance support for mutexes (PTHREAD_PRIO_INHERIT).

2. Ideally, a real-time capable Linux kernel with the PREEMPT_RT
support enabled. Non real-time kernels can be used too, likely for
basic debugging tasks, and/or applications which do not have strict
real-time requirements.

Compiling the Cobalt core
=========================

Same as Xenomai 2.6.x for the in-kernel part. Check out
http://git.xenomai.org/?p=xenomai-head.git;a=blob;f=README.INSTALL;h=f9727c226b58e26b328a572f54712d034b8f8a65;hb=HEAD

Then, configure, build and install the user-space libraries and
executables, passing --with-core=cobalt to the configure script. See
below.

Compiling the Mercury core
==========================

There is no Xenomai-specific kernel bits currently, until we have
enabled the native RTDM support and drivers.  So for now, you just
need to configure, build and install the user-space libraries and
executables, passing --with-core=mercury to the configure script. See
below.

Compiling the user-space libraries and executables (both cores)
===============================================================

This code base has been autoconf-iscated, so building it is pretty
simple, e.g.:

$ mkdir build-dir
$ cd build-dir
$ ../xenomai-forge/configure --with-core=<cobalt|mercury> <other-options>
$ make
$ make install [DESTDIR=/staging/dir]

Where <other-options> may be any standard autoconf switch, such as:

--prefix=<dir>

	To specify the runtime path for the installation of libraries,
	include files, scripts and executables. "make install" installs
	these files to ${DESTDIR}/<dir>.

	This directory defaults to /usr/xenomai.

or Xenomai-specific knobs:

--enable-debug[=full]

	This switch will enable debug mode, causing debug symbols to
	be compiled in the libraries and executables, passing the -g
	flag to the compiler to get debug symbols. When enabled, this
	switch also causes the __XENO_DEBUG__ macro to be defined, for
	both the Xenomai core and the applications getting their C
	compilation flags from the xeno-config script
	(i.e. xeno-config --cflags).  Debug mode is off by default.

	If the full debug level is specified along with this switch,
	-O0 is passed to the compiler, to disable the optimizer. In
	addition, the macro __XENO_DEBUG_FULL__ is also defined.

	Over the Mercury core, enabling debug mode 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.

--enable-assert

	A number of debug assertion statements are wired into the
	Xenomai core, which aim at checking the internal consistency
	of the emulation system during runtime (see man
	assert(3)). Passing --disable-assert to the configure script
	disables built-in assertions. Assertions are enabled by
	default.

--enable-pshared

	Enable shared multi-processing. When enabled, this option
	allows multiple processes to share real-time objects
	(e.g. tasks, semaphores).

--enable-registry

	Some 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 FUSE, which must be available on the target
	system. Building the Xenomai core with the registry support
	requires the FUSE development libraries to be installed on the
	build system.

	When this option is enabled, the emulator creates a file
	hierachy under /mnt/xenomai/<pid> (by default), where you can
	access the internal state of the active real-time
	objects. E.g. looking at the properties of a VxWorks task
	could be done as follows:

	$ cat /mnt/xenomai/12656/vxworks/tasks/windTask 
	name       = windTask
	errno      = 0
	status     = ready
	priority   = 70
	lock_depth = 0

	You may override the default mount point of the registry
	hierarchy by using the --registry-mountpt runtime option (see
	below).

	NOTE: the FUSE-based registry support is still in its early
	stage, and only a few objects are currently exported, only by
	the VxWorks API when running over the Mercury core. This is
	work in progress, so don't expect too much yet.

	When running over the Cobalt core however, the /proc/xenomai
	interface is available for inspecting the core system state
	(i.e. nucleus and RTDM), like with Xenomai 2.x.

--enable-lores-clock

	Enable low resolution clock. By default, both cores are built
	with support for tick-based timing. If you don't actually
	require such support and only use tickless real-time APIs,
	then you can use --disable-lores-clock to optimize out this
	support.

--enable-clock-monotonic-raw

	The Xenomai core 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: Cobalt implements CLOCK_MONOTONIC_RAW, so this clock is
	turned on by default when building with
	--with-core=cobalt. However, the Mercury core turns this off
	by default, since we don't know in advance whether this
	feature exists on the target kernel.

Compiling an application
========================

Like with Xenomai 2.x, you should use the xeno-config script to get
the proper compilation and linker flags related to Xenomai, for
building your application, for whichever core. Here is a Makefile
fragment fetching the compilation and linker flags for building a
VxWorks-based application, over the Xenomai emulator:

	XENO_CONFIG := /usr/xenomai/bin/xeno-config
	CFLAGS := $(shell $(XENO_CONFIG) --skin=vxworks --cflags)
	LDFLAGS := $(shell $(XENO_CONFIG) --skin=vxworks --ldflags)

Running a Xenomai 3.x application
=================================

For Cobalt, you need Xenomai's Cobalt dual kernel bits built in the
target kernel. The build procedure is identical to Xenomai 2.x.

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 ideally complete preemption (PREEMPT_RT)
if your application requires short and bounded latencies.

An application recognises a set of options that may be passed on the
command line, namely:

--<api>-clock-resolution=<ns>

	The clock resolution available with the API, given as a count
	of nano-seconds, i.e. HZ=(1000000000 / ns). <api> is the name
	of one of the existing Xenomai 3.x APIs your application can
	be linked against, e.g. psos, vxworks or alchemy. When your
	application combines multiple APIs, you can pass several
	clock-resolution switches to set them all.

	The default value depends on the API.

--mem-pool-size=<kb>

	The initial size in Kilobytes of the main memory pool. This
	option only makes sense when the TLSF allocator is being used
	(i.e. --enable-debug is not specified when compiling the
	Xenomai core). This is only a hint, since TLSF will increase
	the main pool size dynamically as needed, if needed. However,
	this option may be used to pre-allocate the specified amount
	of memory to the application process, thus avoiding costly
	system calls to extend the data segment of such process
	while operating in time critical mode.

--no-mlock

	Tells the Xenomai core not to lock the process memory while
	initializing. The application will have to handle this task
	when and how it sees fit, in order to avoid the extra latency
	induced by virtual memory paging.  Otherwise,
	mlockall(MCL_CURRENT | MCL_FUTURE) is automatically invoked by
	the Xenomai core as part of the emulator initialization
	duties.

--registry-mountpt=<path>

	Tells the emulator to mount the object registry over the given
	path, instead of /mnt/xenomai/<pid> by default (see the
	--enable-registry switch from the build time options).

--no-registry

	This switch disables registry support at runtime. No real-time
	objects will be exported to /mnt/xenomai/<pid>, despite the
	registry code has been compiled in.

--session=<name>

	Name of the session the new process will be part of (or create
	if not present). This is only useful when --enable-pshared was
	passed at build time, to allow multiple processes to operate
	on remote objects. e.g. allowing a process to post a semaphore
	created by another process within the same session. This is
	done using a common heap area, shared by all processes within
	the same session.

--reset

	Force removal of an older session. This only works if the
	process which created the shared heap for the former session
	has exited, otherwise an error is raised.

--cpu-affinity=<cpu[,cpu]...>

	Set CPU affinity of threads created by the Xenomai core within
	the new process.

--enable-async-cancel

	Allow threads to be cancelled asynchronously. When disabled,
	threads are deleted only when they reach specific cancellation
	points (like system calls). Defaults to enabled.

Available emulators/APIs
========================

VxWorks		See lib/vxworks/README.
		VxWorks is a registered trademark of Wind River
		Systems, Inc (http://www.windriver.com).

pSOS		See lib/psos/README.
		pSOS is a registered trademark of Wind River
		Systems, Inc (http://www.windriver.com).


Alchemy		This is a re-implementation of Xenomai's former "native"
		API, fully rebased on the new RTOS emulation core.
		This is work in progress.

Wed Sep 21 11:54:54 CEST 2011
by <rpm@xenomai.org>