All services from the Cobalt/POSIX library, or which belong to APIs based on the Copperplate library may be restricted to particular calling contexts, or entail specific side-effects.

In dual kernel mode, the Cobalt API underlies all other application-oriented APIs, providing POSIX real-time services over the Cobalt real-time core. Therefore, the information below applies to all application-oriented APIs available with Xenomai, such as the Cobalt/POSIX library, the Alchemy API, and to all RTOS emulators as well. To describe this information, each service documented by this section bears a set of tags when applicable.

The table below matches the tags used throughout the documentation with the description of their meaning for the caller.

Attention

By Xenomai thread, we mean any thread created by a Xenomai API service, including real-time Cobalt/POSIX threads in dual kernel mode. By regular/plain POSIX thread, we mean any thread directly created by the standard glibc-based POSIX service over Mercury or Cobalt (i.e. NPTL/linuxthreads __STD(pthread_create())), excluding such threads which have been promoted to the real-time domain afterwards (aka "shadowed") over Cobalt.

Context tags

Tag	Context on entry
xthread-only	Must be called from a Xenomai thread
xhandler-only	Must be called from a Xenomai handler. See note.
xcontext	May be called from any Xenomai context (thread or handler).
pthread-only	Must be called from a regular POSIX thread
thread-unrestricted	May be called from a Xenomai or regular POSIX thread indifferently
xthread-nowait	May be called from a Xenomai thread unrestricted, or from a regular thread as a non-blocking service only. See note.
unrestricted	May be called from any context previously described

Note

A Xenomai handler is used for callback-based notifications from Copperplate-based APIs, such as timeouts. This context is NOT mapped to a regular Linux signal handler, it is actually underlaid by a special thread context, so that async-unsafe POSIX services may be invoked internally by the API implementation when running on behalf of such handler. Therefore, calling Xenomai API services from asynchronous regular signal handlers is fundamentally unsafe.

Over Cobalt, the main thread is a particular case, which starts as a regular POSIX thread, then is automatically switched to a Cobalt thread as part of the initialization process, before the main() routine is invoked, unless automatic bootstrap was disabled (see http://xenomai.org/2015/05/application-setup-and-init/#Application_entry_CC).

Possible side-effects when running the application over the Cobalt core (i.e. dual kernel configuration)

Note

As a rule of thumb, any service which might block the caller, causes a switch to primary mode if invoked from secondary mode. This rule might not apply in case the service can complete fully from user-space without any syscall entailed, due to a particular optimization (e.g. fast acquisition of semaphore resources directly from user-space in the non-contended case). Therefore, the switch-{primary, secondary} tags denote either services which will always switch the caller to the mode mentioned, or might have to do so, depending on the context. The absence of such tag indicates that such services can complete in either modes and as such will entail no switch.