A set of wrappers and services easing the transition from Xenomai 2.x to 3.x. More...

int	COMPAT__rt_task_create (RT_TASK task, const char name, int stksize, int prio, int mode)
	Create a real-time task (compatibility service). More...

int	COMPAT__rt_task_set_periodic (RT_TASK *task, RTIME idate, RTIME period)
	Make a real-time task periodic (compatibility service). More...

int	COMPAT__rt_alarm_create (RT_ALARM alarm, const char name)
	Create an alarm object (compatibility service). More...

int	rt_alarm_wait (RT_ALARM *alarm)
	Wait for the next alarm shot (compatibility service). More...

int	COMPAT__rt_event_create (RT_EVENT event, const char name, unsigned long ivalue, int mode)
	Create an event flag group. More...

int	COMPAT__rt_event_signal (RT_EVENT *event, unsigned long mask)
	Signal an event. More...

int	COMPAT__rt_event_clear (RT_EVENT event, unsigned long mask, unsigned long mask_r)
	Clear event flags. More...

int	COMPAT__rt_pipe_create (RT_PIPE pipe, const char name, int minor, size_t poolsize)
	Create a message pipe. More...

int	pthread_make_periodic_np (pthread_t thread, struct timespec starttp, struct timespec periodtp)
	Make a thread periodic (compatibility service). More...

int	pthread_wait_np (unsigned long *overruns_r)
	Wait for the next periodic release point (compatibility service) More...

Detailed Description

A set of wrappers and services easing the transition from Xenomai 2.x to 3.x.

This interface provides a source compatibility layer for building applications based on the Xenomai 2.x posix and native APIs over Xenomai 3.x.

Function Documentation

◆ COMPAT__rt_alarm_create()

int COMPAT__rt_alarm_create	(	RT_ALARM *	alarm,
		const char *	name
	)

Create an alarm object (compatibility service).

This routine creates an object triggering an alarm routine at a specified time in the future. Alarms can be periodic or oneshot, depending on the reload interval value passed to rt_alarm_start(). A task can wait for timeouts using the rt_alarm_wait() service.

Parameters

alarm	The address of an alarm descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the alarm. When non-NULL and non-empty, a copy of this string is used for indexing the created alarm into the object registry.

Returns: Zero is returned upon success. Otherwise:

-ENOMEM is returned if the system fails to get memory from the local pool in order to create the alarm.
-EEXIST is returned if the name is conflicting with an already registered alarm.
-EPERM is returned if this service was called from an asynchronous context.

Tags: thread-unrestricted, switch-secondary

Note: Alarms are process-private objects and thus cannot be shared by multiple processes, even if they belong to the same Xenomai session.

Deprecated:: This is a compatibility service from the Transition Kit.

◆ COMPAT__rt_event_clear()

int COMPAT__rt_event_clear	(	RT_EVENT *	event,
		unsigned long	mask,
		unsigned long *	mask_r
	)

Clear event flags.

This call is the legacy form of the rt_event_clear() service, using a long event mask. The new form uses a regular integer to hold the event mask instead.

Parameters

event	The event descriptor.
mask	The set of event flags to be cleared.
mask_r	If non-NULL, mask_r is the address of a memory location which will receive the previous value of the event flag group before the flags are cleared.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if event is not a valid event flag group descriptor.

Tags: unrestricted, switch-primary

Deprecated:: This is a compatibility service from the Transition Kit.

◆ COMPAT__rt_event_create()

int COMPAT__rt_event_create	(	RT_EVENT *	event,
		const char *	name,
		unsigned long	ivalue,
		int	mode
	)

Create an event flag group.

This call is the legacy form of the rt_event_create() service, using a long event mask. The new form uses a regular integer to hold the event mask instead.

Parameters

event	The address of an event descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the event. When non-NULL and non-empty, a copy of this string is used for indexing the created event into the object registry.
ivalue	The initial value of the group's event mask.
mode	The event group creation mode. The following flags can be OR'ed into this bitmask:

EV_FIFO makes tasks pend in FIFO order on the event flag group.
EV_PRIO makes tasks pend in priority order on the event flag group.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if mode is invalid.
-ENOMEM is returned if the system fails to get memory from the main heap in order to create the event flag group.
-EEXIST is returned if the name is conflicting with an already registered event flag group.
-EPERM is returned if this service was called from an asynchronous context.

Tags: thread-unrestricted, switch-secondary

Note: Event flag groups can be shared by multiple processes which belong to the same Xenomai session.

Deprecated:: This is a compatibility service from the Transition Kit.

◆ COMPAT__rt_event_signal()

int COMPAT__rt_event_signal	(	RT_EVENT *	event,
		unsigned long	mask
	)

Signal an event.

This call is the legacy form of the rt_event_signal() service, using a long event mask. The new form uses a regular integer to hold the event mask instead.

Parameters

event	The event descriptor.
mask	The set of events to be posted.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if event is not an event flag group descriptor.

Tags: unrestricted, switch-primary

Deprecated:: This is a compatibility service from the Transition Kit.

◆ COMPAT__rt_pipe_create()

int COMPAT__rt_pipe_create	(	RT_PIPE *	pipe,
		const char *	name,
		int	minor,
		size_t	poolsize
	)

Create a message pipe.

This call is the legacy form of the rt_pipe_create() service, which returns a zero status upon success. The new form returns the minor number assigned to the connection instead, which is useful when P_MINOR_AUTO is specified in the call (see the discussion about the minor parameter).

This service opens a bi-directional communication channel for exchanging messages between Xenomai threads and regular Linux threads. Pipes natively preserve message boundaries, but can also be used in byte-oriented streaming mode from Xenomai to Linux.

rt_pipe_create() always returns immediately, even if no thread has opened the associated special device file yet. On the contrary, the non real-time side could block upon attempt to open the special device file until rt_pipe_create() is issued on the same pipe from a Xenomai thread, unless O_NONBLOCK was given to the open(2) system call.

Parameters

pipe	The address of a pipe descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the pipe. When non-NULL and non-empty, a copy of this string is used for indexing the created pipe into the object registry.

Named pipes are supported through the use of the registry. Passing a valid name parameter when creating a message pipe causes a symbolic link to be created from /proc/xenomai/registry/rtipc/xddp/name to the associated special device (i.e. /dev/rtp*), so that the specific minor information does not need to be known from those processes for opening the proper device file. In such a case, both sides of the pipe only need to agree upon a symbolic name to refer to the same data path, which is especially useful whenever the minor number is picked up dynamically using an adaptive algorithm, such as passing P_MINOR_AUTO as minor value.

Parameters

minor	The minor number of the device associated with the pipe. Passing P_MINOR_AUTO causes the minor number to be auto-allocated. In such a case, a symbolic link will be automatically created from /proc/xenomai/registry/rtipc/xddp/name to the allocated pipe device entry. Valid minor numbers range from 0 to CONFIG_XENO_OPT_PIPE_NRDEV-1.
poolsize	Specifies the size of a dedicated buffer pool for the pipe. Passing 0 means that all message allocations for this pipe are performed on the Cobalt core heap.

Returns: This compatibility call returns zero upon success. Otherwise:

-ENOMEM is returned if the system fails to get memory from the main heap in order to create the pipe.
-ENODEV is returned if minor is different from P_MINOR_AUTO and is not a valid minor number.
-EEXIST is returned if the name is conflicting with an already registered pipe.
-EBUSY is returned if minor is already open.
-EPERM is returned if this service was called from an asynchronous context.

Tags: thread-unrestricted, switch-secondary

◆ COMPAT__rt_task_create()

int COMPAT__rt_task_create	(	RT_TASK *	task,
		const char *	name,
		int	stksize,
		int	prio,
		int	mode
	)

Create a real-time task (compatibility service).

This service creates a task with access to the full set of Xenomai real-time services.

This service creates a task with access to the full set of Xenomai real-time services. If prio is non-zero, the new task belongs to Xenomai's real-time FIFO scheduling class, aka SCHED_FIFO. If prio is zero, the task belongs to the regular SCHED_OTHER class.

Creating tasks with zero priority is useful for running non real-time processes which may invoke blocking real-time services, such as pending on a semaphore, reading from a message queue or a buffer, and so on.

Once created, the task is left dormant until it is actually started by rt_task_start().

Parameters

task	The address of a task descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the task. When non-NULL and non-empty, a copy of this string is used for indexing the created task into the object registry.
stksize	The size of the stack (in bytes) for the new task. If zero is passed, a system-dependent default size will be substituted.
prio	The base priority of the new task. This value must be in the [0 .. 99] range, where 0 is the lowest effective priority.
mode	The task creation mode. The following flags can be OR'ed into this bitmask:

T_FPU allows the task to use the FPU whenever available on the platform. This flag may be omitted, as it is automatically set when a FPU is present on the platform, cleared otherwise.
T_SUSP causes the task to start in suspended mode. In such a case, the thread will have to be explicitly resumed using the rt_task_resume() service for its execution to actually begin.
T_CPU(cpuid) makes the new task affine to CPU # cpuid. CPU identifiers range from 0 to 7 (inclusive).
T_JOINABLE allows another task to wait on the termination of the new task. rt_task_join() shall be called for this task to clean up any resources after its termination.

Passing T_FPU|T_CPU(1) in the mode parameter thus creates a task with FPU support enabled and which will be affine to CPU #1.

When running over the Cobalt core, T_WARNSW causes the SIGDEBUG signal to be sent to the current task whenever it switches to the secondary mode. This feature is useful to detect unwanted migrations to the Linux domain. This flag has no effect over the Mercury core.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if either prio, mode or stksize are invalid.
-ENOMEM is returned if the system fails to get memory from the main heap in order to create the task.
-EEXIST is returned if the name is conflicting with an already registered task.

Tags: thread-unrestricted, switch-secondary

Side effects

calling rt_task_create() causes SCHED_FIFO tasks to switch to secondary mode.
members of Xenomai's SCHED_FIFO class running in the primary domain have utmost priority over all Linux activities in the system, including Linux interrupt handlers.

Note: Tasks can be referred to from multiple processes which all belong to the same Xenomai session.

Deprecated:: This is a compatibility service from the Transition Kit.

◆ COMPAT__rt_task_set_periodic()

int COMPAT__rt_task_set_periodic	(	RT_TASK *	task,
		RTIME	idate,
		RTIME	period
	)

Make a real-time task periodic (compatibility service).

Make a task periodic by programing its first release point and its period in the processor time line. task should then call rt_task_wait_period() to sleep until the next periodic release point in the processor timeline is reached.

Parameters

task	The task descriptor. If task is NULL, the current task is made periodic. task must belong the current process.
idate	The initial (absolute) date of the first release point, expressed in clock ticks (see note). If idate is equal to TM_NOW, the current system date is used. Otherwise, if task is NULL or equal to rt_task_self(), the caller is delayed until idate has elapsed.
period	The period of the task, expressed in clock ticks (see note). Passing TM_INFINITE stops the task's periodic timer if enabled, then returns successfully.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is NULL but the caller is not a Xenomai task, or if task is non-NULL but not a valid task descriptor.
-ETIMEDOUT is returned if idate is different from TM_INFINITE and represents a date in the past.

Tags: thread-unrestricted, switch-primary

Note: The caller must be an Alchemy task if task is NULL.; Unlike the original Xenomai 2.x call, this emulation delays the caller until idate has elapsed only if task is NULL or equal to rt_task_self().

Side effects: Over Cobalt, -EINVAL is returned if period is different from TM_INFINITE but shorter than the user scheduling latency value for the target system, as displayed by /proc/xenomai/latency.

Note: The idate and period values are interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

Deprecated:: This is a compatibility service from the Transition Kit.

◆ pthread_make_periodic_np()

int pthread_make_periodic_np	(	pthread_t	thread,
		struct timespec *	starttp,
		struct timespec *	periodtp
	)

Make a thread periodic (compatibility service).

This service makes the POSIX thread periodic.

Parameters

thread	thread to arm a periodic timer for.
starttp	start time, expressed as an absolute value of the CLOCK_REALTIME clock.
periodtp	period, expressed as a time interval.

Returns

0 on success;

an error number if:

ESRCH, thread is invalid.
ETIMEDOUT, the start time has already passed.
EPERM, the caller is not a Xenomai thread.
EINVAL, thread does not refer to the current thread.

Note: Unlike the original Xenomai 2.x call, this emulation does not delay the caller waiting for the first periodic release point. In addition, thread must be equal to pthread_self().

Deprecated:: This service is a non-portable extension of the Xenomai 2.x POSIX interface, not available with Xenomai 3.x. Instead, Cobalt-based applications should set up a periodic timer using the timer_create(), timer_settime() call pair, then wait for release points via sigwaitinfo(). Overruns can be detected by looking at the siginfo.si_overrun field. Alternatively, applications may obtain a file descriptor referring to a Cobalt timer via the timerfd() call, and read() from it to wait for timeouts.

References timer_create(), and timer_settime().

◆ pthread_wait_np()

int pthread_wait_np ( unsigned long * overruns_r )

Wait for the next periodic release point (compatibility service)

Delay the current thread until the next periodic release point is reached. The periodic timer should have been previously started for thread by a call to pthread_make_periodic_np().

Parameters

overruns_r If non-NULL, overruns_r shall be a pointer to a memory location which will be written with the count of pending overruns. This value is written to only when pthread_wait_np() returns ETIMEDOUT or success. The memory location remains unmodified otherwise. If NULL, this count will not be returned.

Returns: Zero is returned upon success. If overruns_r is non-NULL, zero is written to the pointed memory location. Otherwise:

EWOULDBLOCK is returned if pthread_make_periodic_np() was not called for the current thread.
EINTR is returned if thread was interrupted by a signal before the next periodic release point was reached.
ETIMEDOUT is returned if a timer overrun occurred, which indicates that a previous release point was missed by the calling thread. If overruns_r is non-NULL, the count of pending overruns is written to the pointed memory location.
EPERM is returned if this service was called from an invalid context.

Note: If the current release point has already been reached at the time of the call, the current thread immediately returns from this service with no delay.

Deprecated:: This service is a non-portable extension of the Xenomai 2.x POSIX interface, not available with Xenomai 3.x. Instead, Cobalt-based applications should set up a periodic timer using the timer_create(), timer_settime() call pair, then wait for release points via sigwaitinfo(). Overruns can be detected by looking at the siginfo.si_overrun field. Alternatively, applications may obtain a file descriptor referring to a Cobalt timer via the timerfd() call, and read() from it to wait for timeouts.

◆ rt_alarm_wait()

int rt_alarm_wait ( RT_ALARM * alarm )

Wait for the next alarm shot (compatibility service).

This service allows the current task to suspend execution until the specified alarm triggers. The priority of the current task is raised above all other tasks - except those also undergoing an alarm wait.

Returns: Zero is returned upon success, after the alarm timed out. Otherwise:

-EINVAL is returned if alarm is not a valid alarm descriptor.
-EPERM is returned if this service was called from an invalid context.
-EINTR is returned if rt_task_unblock() was called for the current task before the request is satisfied.
-EIDRM is returned if alarm is deleted while the caller was sleeping on it. In such a case, alarm is no more valid upon return of this service.

Tags: xthread-only, switch-primary

Deprecated:: This is a compatibility service from the Transition Kit.