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.