Xenomai  3.0-rc7
API service tags

The non-POSIX API services based on the Copperplate library may be restricted to particular calling contexts, or entail specific side-effects.

This information applies to the Alchemy API services, 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.

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 most often used for callback-based timeout notifications. 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.
A non-blocking call for an API service is defined by a special value passed as a timeout specification.
Possible side-effects over the Cobalt core (i.e. dual kernel configuration)
Tag Description
switch-primary the caller may switch to primary mode
switch-secondary the caller may switch to secondary mode
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.