Collaboration diagram for Task management services.:

Files
file	task.c
	This file is part of the Xenomai project.
Functions
int	rt_task_create (RT_TASK task, const char name, int stksize, int prio, int mode)
	Create a new real-time task.
int	rt_task_start (RT_TASK task, void(entry)(void cookie), void cookie)
	Start a real-time task.
int	rt_task_suspend (RT_TASK *task)
	Suspend a real-time task.
int	rt_task_resume (RT_TASK *task)
	Resume a real-time task.
int	rt_task_delete (RT_TASK *task)
	Delete a real-time task.
int	rt_task_yield (void)
	Manual round-robin.
int	rt_task_set_periodic (RT_TASK *task, RTIME idate, RTIME period)
	Make a real-time task periodic.
int	rt_task_wait_period (unsigned long *overruns_r)
	Wait for the next periodic release point.
int	rt_task_set_priority (RT_TASK *task, int prio)
	Change the base priority of a real-time task.
int	rt_task_sleep (RTIME delay)
	Delay the calling task (relative).
int	rt_task_sleep_until (RTIME date)
	Delay the calling task (absolute).
int	rt_task_unblock (RT_TASK *task)
	Unblock a real-time task.
int	rt_task_inquire (RT_TASK task, RT_TASK_INFO info)
	Inquire about a real-time task.
int	rt_task_add_hook (int type, void(routine)(void cookie))
	Install a task hook.
int	rt_task_remove_hook (int type, void(routine)(void cookie))
	Remove a task hook.
int	rt_task_catch (void(*handler)(rt_sigset_t))
	Install a signal handler.
int	rt_task_notify (RT_TASK *task, rt_sigset_t signals)
	Send signals to a task.
int	rt_task_set_mode (int clrmask, int setmask, int *mode_r)
	Change task mode bits.
RT_TASK *	rt_task_self (void)
	Retrieve the current task.
int	rt_task_slice (RT_TASK *task, RTIME quantum)
	Set a task's round-robin quantum.
ssize_t	rt_task_send (RT_TASK task, RT_TASK_MCB mcb_s, RT_TASK_MCB *mcb_r, RTIME timeout)
	Send a message to a task.
int	rt_task_receive (RT_TASK_MCB *mcb_r, RTIME timeout)
	Receive a message from a task.
int	rt_task_reply (int flowid, RT_TASK_MCB *mcb_s)
	Reply to a task.
static int	rt_task_spawn (RT_TASK task, const char name, int stksize, int prio, int mode, void(entry)(void cookie), void *cookie)
	Spawn a new real-time task.
int	rt_task_shadow (RT_TASK task, const char name, int prio, int mode)
	Turns the current Linux task into a native Xenomai task.
int	rt_task_bind (RT_TASK task, const char name, RTIME timeout)
	Bind to a real-time task.
static int	rt_task_unbind (RT_TASK *task)
	Unbind from a real-time task.
int	rt_task_join (RT_TASK *task)
	Wait on the termination of a real-time task.
int	rt_task_same (RT_TASK task1, RT_TASK task2)
	Compare two task descriptors.

Detailed Description

Xenomai provides a set of multitasking mechanisms. The basic process object performing actions in Xenomai is a task, a logically complete path of application code. Each Xenomai task is an independent portion of the overall application code embodied in a C procedure, which executes on its own stack context.

The Xenomai scheduler ensures that concurrent tasks are run according to one of the supported scheduling policies. Currently, the Xenomai scheduler supports fixed priority-based FIFO and round-robin policies.

Function Documentation

int rt_task_add_hook	(	int	type,
		void()(void cookie)	routine
	)

Install a task hook.

The real-time kernel allows to register user-defined routines which get called whenever a specific scheduling event occurs. Multiple hooks can be chained for a single event type, and get called on a FIFO basis.

The scheduling is locked while a hook is executing.

Parameters:

type	Defines the kind of hook to install:

T_HOOK_START: The user-defined routine will be called on behalf of the starter task whenever a new task starts. An opaque cookie is passed to the routine which can use it to retrieve the descriptor address of the started task through the T_DESC() macro.

T_HOOK_DELETE: The user-defined routine will be called on behalf of the deletor task whenever a task is deleted. An opaque cookie is passed to the routine which can use it to retrieve the descriptor address of the deleted task through the T_DESC() macro.

T_HOOK_SWITCH: The user-defined routine will be called on behalf of the resuming task whenever a context switch takes place. An opaque cookie is passed to the routine which can use it to retrieve the descriptor address of the task which has been switched in through the T_DESC() macro.

Parameters:

routine The address of the user-supplied routine to call.

Returns:: 0 is returned upon success. Otherwise, one of the following error codes indicates the cause of the failure:

-EINVAL is returned if type is incorrect.

-ENOMEM is returned if not enough memory is available from the system heap to add the new hook.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine
Kernel-based task

Rescheduling: never.

References xnpod_add_hook().

int rt_task_bind	(	RT_TASK *	task,
		const char *	name,
		RTIME	timeout
	)

Bind to a real-time task.

This user-space only service retrieves the uniform descriptor of a given Xenomai task identified by its symbolic name. If the task does not exist on entry, this service blocks the caller until a task of the given name is created.

Parameters:

name	A valid NULL-terminated name which identifies the task to bind to.
task	The address of a task descriptor retrieved by the operation. Contents of this memory is undefined upon failure.
timeout	The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.

Returns:: 0 is returned upon success. Otherwise:

-EFAULT is returned if task or name is referencing invalid memory.

-EINTR is returned if rt_task_unblock() has been called for the waiting task before the retrieval has completed.

-EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.

-ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.

-EPERM is returned if this service should block, but was called from a context which cannot sleep (e.g. interrupt, non-realtime context).

Environments:

This service can be called from:

User-space task (switches to primary mode)

Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Note:: The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

Examples:: bound_task.c.

int rt_task_catch ( void(*)(rt_sigset_t) handler )

Install a signal handler.

This service installs a signal handler for the current task. Signals are discrete events tasks can receive each time they resume execution. When signals are pending upon resumption, handler is fired to process them. Signals can be sent using rt_task_notify(). A task can block the signal delivery by passing the T_NOSIG bit to rt_task_set_mode().

Calling this service implicitely unblocks the signal delivery for the caller.

Parameters:

handler The address of the user-supplied routine to fire when signals are pending for the task. This handler is passed the set of pending signals as its first and only argument.

Returns:: 0 upon success, or:

-EPERM is returned if this service was not called from a real-time task context.

Environments:

This service can be called from:

Kernel-based task

Rescheduling: possible.

References XNASDI, and xnpod_schedule().

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

Create a new real-time task.

Creates a real-time task, either running in a kernel module or in user-space depending on the caller's context.

Parameters:

task	The address of a task descriptor Xenomai will use to store the task-related data. This descriptor must always be valid while the task is active therefore it must be allocated in permanent memory.

The task is left in an innocuous state until it is actually started by rt_task_start().

Parameters:

name	An ASCII string standing for the symbolic name of the task. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created task.
stksize	The size of the stack (in bytes) for the new task. If zero is passed, a reasonable pre-defined size will be substituted.
prio	The base priority of the new task. This value must range from [0 .. 99] (inclusive) where 0 is the lowest effective priority.
mode	The task creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new task:

T_FPU allows the task to use the FPU whenever available on the platform. This flag is forced for user-space tasks.

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 RTHAL_NR_CPUS - 1 (inclusive).

T_JOINABLE (user-space only) allows another task to wait on the termination of the new task. This implies that rt_task_join() is actually called for this task to clean up any user-space located 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.

Returns:: 0 is returned upon success. Otherwise:

-ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to create or register the task.

-EEXIST is returned if the name is already in use by some registered object.

-EPERM is returned if this service was called from an asynchronous context.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: possible.

Note:

When creating or shadowing a Xenomai thread for the first time in user-space, Xenomai installs a handler for the SIGWINCH signal. If you had installed a handler before that, it will be automatically called by Xenomai for SIGWINCH signals that it has not sent.

If, however, you install a signal handler for SIGWINCH after creating or shadowing the first Xenomai thread, you have to explicitly call the function xeno_sigwinch_handler at the beginning of your signal handler, using its return to know if the signal was in fact an internal signal of Xenomai (in which case it returns 1), or if you should handle the signal (in which case it returns 0). xeno_sigwinch_handler prototype is:

int xeno_sigwinch_handler(int sig, siginfo_t *si, void *ctxt);

Which means that you should register your handler with sigaction, using the SA_SIGINFO flag, and pass all the arguments you received to xeno_sigwinch_handler.

References pthread_attr_init(), pthread_attr_setdetachstate(), pthread_attr_setinheritsched(), pthread_attr_setschedparam(), pthread_attr_setschedpolicy(), pthread_attr_setstacksize(), pthread_join(), XNFPU, xnheap_alloc(), xnheap_free(), xnpod_delete_thread(), xnpod_init_thread(), XNSHADOW, XNSUSP, and xnsynch_init().

Referenced by rt_task_spawn().

int rt_task_delete ( RT_TASK * task )

Delete a real-time task.

Terminate a task and release all the real-time kernel resources it currently holds. A task exists in the system since rt_task_create() has been called to create it, so this service must be called in order to destroy it afterwards.

Native tasks implement a mechanism by which they are immune from deletion by other tasks while they run into a deemed safe section of code. This feature is used internally by the native skin in order to prevent tasks from being deleted in the middle of a critical section, without resorting to interrupt masking when the latter is not an option. For this reason, the caller of rt_task_delete() might be blocked and a rescheduling take place, waiting for the target task to exit such critical section.

The DELETE hooks are called on behalf of the calling context (if any). The information stored in the task control block remains valid until all hooks have been called.

Parameters:

task	The descriptor address of the affected task. If task is NULL, the current task is deleted.

Returns:: 0 is returned upon success. Otherwise:

-EINVAL is returned if task is not a task descriptor.

-EPERM is returned if task is NULL but not called from a task context, or this service was called from an asynchronous context.

-EINTR is returned if rt_task_unblock() has been invoked for the caller while it was waiting for task to exit a safe section. In such a case, the deletion process has been aborted and task remains unaffected.

-EIDRM is returned if task is a deleted task descriptor.

Environments:

This service can be called from:

Kernel module initialization/cleanup code only if task is non-NULL.

Kernel-based task
Any user-space context (conforming call)

Rescheduling: always if task is NULL, and possible if the deleted task is currently running into a safe section.

Note:: A task that was successfully joined via rt_task_join() must not be explicitly deleted afterwards. However, invoking rt_task_join() remains mandatory for every joinable task even after calling rt_task_delete().

References pthread_cancel(), pthread_exit(), rt_task_self(), xnheap_free(), and xnpod_delete_thread().

int rt_task_inquire	(	RT_TASK *	task,
		RT_TASK_INFO *	info
	)

Inquire about a real-time task.

Return various information about the status of a given task.

Parameters:

task	The descriptor address of the inquired task. If task is NULL, the current task is inquired.
info	The address of a structure the task information will be written to. Passing NULL is valid, in which case the system is only probed for existence of the specified task.

Returns:: 0 is returned if the task exists, and status information is written to the structure pointed at by info if non-NULL. Otherwise:

-EINVAL is returned if task is not a task descriptor.

-EPERM is returned if task is NULL but not called from a task context.

-EIDRM is returned if task is a deleted task descriptor.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine only if task is non-NULL.

Kernel-based task
User-space task

Rescheduling: never.

References rt_task_info::bprio, rt_task_info::cprio, rt_task_info::ctxswitches, rt_task_info::exectime, rt_task_info::modeswitches, rt_task_info::name, rt_task_info::pagefaults, rt_task_info::relpoint, rt_task_info::status, and xntimer_get_date().

int rt_task_join ( RT_TASK * task )

Wait on the termination of a real-time task.

This user-space only service blocks the caller in non-real-time context until task has terminated. All real-time kernel resources are released after successful completion of this service. Note that the specified task must have been created by the same process that wants to join it, and the T_JOINABLE mode flag must have been set on creation.

Parameters:

task	The address of a task descriptor to join.

Returns:: 0 is returned upon success. Otherwise:

-EINVAL is returned if the task was not created with T_JOINABLE set or some other task is already waiting on the termination.

-EDEADLK is returned if task refers to the caller.

-ESRCH is returned if task no longer exists or refers to task created by a different process.

This service can be called from:

User-space task.

Rescheduling: always unless the task was already terminated.

Note:: After successful completion of this service it is neither required nor valid to additionally invoke rt_task_delete() on the same task.

References pthread_join().

int rt_task_notify	(	RT_TASK *	task,
		rt_sigset_t	signals
	)

Send signals to a task.

This service sends a set of signals to a given task. A task can install a signal handler using the rt_task_catch() service to process them.

Parameters:

task	The descriptor address of the affected task which must have been previously created by the rt_task_create() service.
signals	The set of signals to make pending for the task. This set is OR'ed with the current set of pending signals for the task; there is no count of occurence maintained for each available signal, which is either pending or cleared.

Returns:: 0 is returned upon success. Otherwise:

-EINVAL is returned if task is not a task descriptor.

-EPERM is returned if task is NULL but not called from a real-time task context.

-EIDRM is returned if task is a deleted task descriptor.

-ESRCH is returned if task has not set any signal handler.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine only if task is non-NULL.

Kernel-based task
User-space task

Rescheduling: possible.

References xnpod_schedule().

int rt_task_receive	(	RT_TASK_MCB *	mcb_r,
		RTIME	timeout
	)

Receive a message from a task.

This service is part of the synchronous message passing support available to Xenomai tasks. It allows the caller to receive a variable-sized message sent from another task using the rt_task_send() service. The sending task is blocked until the caller invokes rt_task_reply() to finish the transaction.

A basic message control block is used to store the location and size of the data area to receive from the client, in addition to a user-defined operation code.

Parameters:

mcb_r The address of a message control block referring to the receive message area. The fields from this control block should be set as follows:

mcb_r->data should contain the address of a buffer large enough to collect the data sent by the remote task;

mcb_r->size should contain the size in bytes of the buffer space pointed at by mcb_r->data. If mcb_r->size is lower than the actual size of the received message, no data copy takes place and -ENOBUFS is returned to the caller. See note.

Upon return, mcb_r->opcode will contain the operation code sent from the remote task using rt_task_send().

Parameters:

timeout The number of clock ticks to wait for receiving a message (see note). Passing TM_INFINITE causes the caller to block indefinitely until a remote task eventually sends a message. Passing TM_NONBLOCK causes the service to return immediately without waiting if no remote task is currently waiting for sending a message.

Returns:: A strictly positive value is returned upon success, representing a flow identifier for the opening transaction; this token should be passed to rt_task_reply(), in order to send back a reply to and unblock the remote task appropriately. Otherwise:

-ENOBUFS is returned if mcb_r does not point at a message area large enough to collect the remote task's message.

-EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and no remote task is currently waiting for sending a message to the caller.

-ETIMEDOUT is returned if no message was received within the timeout.

-EINTR is returned if rt_task_unblock() has been called for the caller before any message was available.

-EPERM is returned if this service was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).

Environments:

This service can be called from:

Kernel-based task
User-space task (switches to primary mode)

Rescheduling: Always.

Note:: The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.; When called from a user-space task, this service may need to allocate some temporary buffer space from the system heap to hold the received data if the size of the latter exceeds a certain amount; the threshold before allocation is currently set to 64 bytes.

References rt_task_mcb::data, rt_task_mcb::opcode, rt_task_mcb::size, XNBREAK, xnsynch_sleep_on(), and XNTIMEO.

int rt_task_remove_hook	(	int	type,
		void()(void cookie)	routine
	)

Remove a task hook.

This service allows to remove a task hook previously registered using rt_task_add_hook().

Parameters:

type	Defines the kind of hook to uninstall. Possible values are:

T_HOOK_START
T_HOOK_DELETE
T_HOOK_SWITCH

Parameters:

routine The address of the user-supplied routine to remove from the hook list.

Returns:: 0 is returned upon success. Otherwise, one of the following error codes indicates the cause of the failure:

-EINVAL is returned if type is incorrect.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine
Kernel-based task

Rescheduling: never.

References xnpod_remove_hook().

int rt_task_reply	(	int	flowid,
		RT_TASK_MCB *	mcb_s
	)

Reply to a task.

This service is part of the synchronous message passing support available to Xenomai tasks. It allows the caller to send back a variable-sized message to the client task, once the initial message from this task has been pulled using rt_task_receive() and processed. As a consequence of this call, the remote task will be unblocked from the rt_task_send() service.

A basic message control block is used to store the location and size of the data area to send back, in addition to a user-defined status code.

Parameters:

flowid	The flow identifier returned by a previous call to rt_task_receive() which uniquely identifies the current transaction.
mcb_s	The address of an optional message control block referring to the message to be sent back. If mcb_s is NULL, the client will be unblocked without getting any reply data. When mcb_s is valid, the fields from this control block should be set as follows:

mcb_s->data should contain the address of the payload data to send to the remote task.

mcb_s->size should contain the size in bytes of the payload data pointed at by mcb_s->data. 0 is a legitimate value, and indicates that no payload data will be transferred. In the latter case, mcb_s->data will be ignored. See note.

mcb_s->opcode is an opaque status code carried during the message transfer the caller can fill with any appropriate value. It will be made available "as is" to the remote task into the status code field by the rt_task_send() service. If mcb_s is NULL, 0 will be returned to the client into the status code field.

Returns:: Zero is returned upon success. Otherwise:

-EINVAL is returned if flowid is invalid.

-ENXIO is returned if flowid does not match the expected identifier returned from the latest call of the current task to rt_task_receive(), or if the remote task stopped waiting for the reply in the meantime (e.g. the client could have been deleted or forcibly unblocked).

-EPERM is returned if this service was called from an invalid context (e.g. interrupt, or non-primary).

Environments:

This service can be called from:

Kernel-based task
User-space task (switches to primary mode)

Rescheduling: Always.

Note:: When called from a user-space task, this service may need to allocate some temporary buffer space from the system heap to hold the reply data if the size of the latter exceeds a certain amount; the threshold before allocation is currently set to 64 bytes.

References rt_task_mcb::data, rt_task_mcb::opcode, rt_task_mcb::size, xnpod_schedule(), and xnpod_unblock_thread().

int rt_task_resume ( RT_TASK * task )

Resume a real-time task.

Forcibly resume the execution of a task which has been previously suspended by a call to rt_task_suspend().

The suspension nesting count is decremented so that rt_task_resume() will only resume the task if this count falls down to zero as a result of the current invocation.

Parameters:

task	The descriptor address of the affected task.

Returns:: 0 is returned upon success. Otherwise:

-EINVAL is returned if task is not a task descriptor.

-EIDRM is returned if task is a deleted task descriptor.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine
Kernel-based task
User-space task

Rescheduling: possible if the suspension nesting level falls down to zero as a result of the current invocation.

References xnpod_resume_thread(), xnpod_schedule(), and XNSUSP.

int rt_task_same	(	RT_TASK *	task1,
		RT_TASK *	task2
	)

Compare two task descriptors.

This service checks whether two task descriptors refer to the same task. This service is particularly useful in user-space, since rt_task_self() does return a task descriptor which is different from the original descriptor used by the application, but still refers to the same task internally.

Parameters:

task1	The address of the first task descriptor to compare.
task2	The address of the second task descriptor to compare.

Returns:: non-zero whenever the two task descriptors refer to the same task, zero otherwise.

This service can be called from:

Kernel-based task.
User-space task.

Rescheduling: never.

RT_TASK* rt_task_self ( void )

Retrieve the current task.

Return the current task descriptor address.

Returns:: The address of the caller's task descriptor is returned upon success, or NULL if the calling context is asynchronous (i.e. not a Xenomai task).

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine Those will cause a NULL return.

Kernel-based task
User-space task

Rescheduling: never.

References pthread_getspecific().

Referenced by rt_task_delete().

ssize_t rt_task_send	(	RT_TASK *	task,
		RT_TASK_MCB *	mcb_s,
		RT_TASK_MCB *	mcb_r,
		RTIME	timeout
	)

Send a message to a task.

This service is part of the synchronous message passing support available to Xenomai tasks. It allows the caller to send a variable-sized message to another task, waiting for the remote to receive the initial message by a call to rt_task_receive(), then reply to it using rt_task_reply().

A basic message control block is used to store the location and size of the data area to send or retrieve upon reply, in addition to a user-defined operation code.

Parameters:

task	The descriptor address of the recipient task.
mcb_s	The address of the message control block referring to the message to be sent. The fields from this control block should be set as follows:

mcb_s->data should contain the address of the payload data to send to the remote task.

mcb_s->size should contain the size in bytes of the payload data pointed at by mcb_s->data. 0 is a legitimate value, and indicates that no payload data will be transferred. In the latter case, mcb_s->data will be ignored. See note.

mcb_s->opcode is an opaque operation code carried during the message transfer the caller can fill with any appropriate value. It will be made available "as is" to the remote task into the operation code field by the rt_task_receive() service.

Parameters:

mcb_r The address of an optional message control block referring to the reply message area. If mcb_r is NULL and a reply is sent back by the remote task, the reply message will be discarded, and -ENOBUFS will be returned to the caller. When mcb_r is valid, the fields from this control block should be set as follows:

mcb_r->data should contain the address of a buffer large enough to collect the reply data from the remote task.

mcb_r->size should contain the size in bytes of the buffer space pointed at by mcb_r->data. If mcb_r->size is lower than the actual size of the reply message, no data copy takes place and -ENOBUFS is returned to the caller. See note.

Upon return, mcb_r->opcode will contain the status code sent back from the remote task using rt_task_reply(), or 0 if unspecified.

Parameters:

timeout The number of clock ticks to wait for the remote task to reply to the initial message (see note). Passing TM_INFINITE causes the caller to block indefinitely until the remote task eventually replies. Passing TM_NONBLOCK causes the service to return immediately without waiting if the remote task is not waiting for messages (i.e. if task is not currently blocked on the rt_task_receive() service); however, the caller will wait indefinitely for a reply from that remote task if present.

Returns:: A positive value is returned upon success, representing the length (in bytes) of the reply message returned by the remote task. 0 is a success status, meaning either that mcb_r was NULL on entry, or that no actual message was passed to the remote call to rt_task_reply(). Otherwise:

-ENOBUFS is returned if mcb_r does not point at a message area large enough to collect the remote task's reply. This includes the case where mcb_r is NULL on entry albeit the remote task attempts to send a reply message.

-EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and task is not currently blocked on the rt_task_receive() service.

-EIDRM is returned if task has been deleted while waiting for a reply.

-EINTR is returned if rt_task_unblock() has been called for the caller before any reply was available.

-EPERM is returned if this service should block, but was called from a context which cannot sleep (e.g. interrupt, non-realtime context).

-ESRCH is returned if task cannot be found (when called from user-space only).

Environments:

This service can be called from:

Kernel-based task
User-space task (switches to primary mode)

Rescheduling: Always.

Note:: The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.; When called from a user-space task, this service may need to allocate some temporary buffer space from the system heap to hold both the sent and the reply data if this cumulated size exceeds a certain amount; the threshold before allocation is currently set to 64 bytes.

References rt_task_mcb::data, rt_task_mcb::flowid, rt_task_mcb::opcode, pthread_setcanceltype(), rt_task_mcb::size, XNBREAK, XNRMID, xnsynch_acquire(), xnsynch_flush(), and XNTIMEO.

int rt_task_set_mode	(	int	clrmask,
		int	setmask,
		int *	mode_r
	)

Change task mode bits.

Each Xenomai task has a set of internal bits determining various operating conditions; the rt_task_set_mode() service allows to alter three of them, respectively controlling:

whether the task locks the rescheduling procedure,
whether the task undergoes a round-robin scheduling,
whether the task blocks the delivery of signals.

To this end, rt_task_set_mode() takes a bitmask of mode bits to clear for disabling the corresponding modes, and another one to set for enabling them. The mode bits which were previously in effect can be returned upon request.

The following bits can be part of the bitmask:

T_LOCK causes the current task to lock the scheduler. Clearing this bit unlocks the scheduler.

T_NOSIG disables the asynchronous signal delivery for the current task.

When set, T_WARNSW causes the SIGXCPU signal to be sent to the current user-space task whenever it switches to the secondary mode. This feature is useful to detect unwanted migrations to the Linux domain.

T_RPIOFF disables thread priority coupling between Xenomai and Linux schedulers. This bit prevents the root Linux thread from inheriting the priority of the running shadow Xenomai thread. Use CONFIG_XENO_OPT_RPIOFF to globally disable priority coupling.

T_PRIMARY can be passed to switch the current user-space task to primary mode (setmask |= T_PRIMARY), or secondary mode (clrmask |= T_PRIMARY). Upon return from rt_task_set_mode(), the user-space task will run into the specified domain.

Normally, this service can only be called on behalf of a regular real-time task, either running in kernel or user-space. However, as a special exception, requests for setting/clearing the T_LOCK bit from asynchronous contexts are silently dropped, and the call returns successfully if no other mode bits have been specified. This is consistent with the fact that Xenomai enforces a scheduler lock until the outer interrupt handler has returned.

Parameters:

clrmask	A bitmask of mode bits to clear for the current task, before setmask is applied. 0 is an acceptable value which leads to a no-op.
setmask	A bitmask of mode bits to set for the current task. 0 is an acceptable value which leads to a no-op.
mode_r	If non-NULL, mode_r must be a pointer to a memory location which will be written upon success with the previous set of active mode bits. If NULL, the previous set of active mode bits will not be returned.

Returns:: 0 is returned upon success, or:

-EINVAL if either setmask or clrmask specifies invalid bits. T_PRIMARY is invalid for kernel-based tasks.

-EPERM is returned if this service was not called from a real-time task context.

Environments:

This service can be called from:

Kernel-based task
User-space task

Rescheduling: possible, if T_LOCK has been passed into clrmask and the calling context is a task.

References T_LOCK, T_NOSIG, T_RPIOFF, T_WARNSW, xnpod_schedule(), and xnpod_set_thread_mode().

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

Make a real-time task periodic.

Make a task periodic by programing its first release point and its period in the processor time line. Subsequent calls to rt_task_wait_period() will delay the task until the next periodic release point in the processor timeline is reached.

Parameters:

task	The descriptor address of the affected task. This task is immediately delayed until the first periodic release point is reached. If task is NULL, the current task is set periodic.
idate	The initial (absolute) date of the first release point, expressed in clock ticks (see note). The affected task will be delayed until this point is reached. If idate is equal to TM_NOW, the current system date is used, and no initial delay takes place.
period	The period of the task, expressed in clock ticks (see note). Passing TM_INFINITE attempts to stop the task's periodic timer; in the latter case, the routine always exits succesfully, regardless of the previous state of this timer.

Returns:: 0 is returned upon success. Otherwise:

-EINVAL is returned if task is not a task descriptor, or period is different from TM_INFINITE but shorter than the scheduling latency value for the target system, as available from /proc/xenomai/latency.

-EIDRM is returned if task is a deleted task descriptor.

-ETIMEDOUT is returned if idate is different from TM_INFINITE and represents a date in the past.

-EWOULDBLOCK is returned if the system timer is not active.

-EPERM is returned if task is NULL but not called from a task context.

Environments:

This service can be called from:

Kernel module initialization/cleanup code or interrupt only if task is non-NULL.

Kernel-based task
User-space task (switches to primary mode)

Rescheduling: always if the operation affects the current task and idate has not elapsed yet.

Note:: The idate and period values will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

References xnpod_set_thread_periodic().

int rt_task_set_priority	(	RT_TASK *	task,
		int	prio
	)

Change the base priority of a real-time task.

Changing the base priority of a task does not affect the priority boost the target task might have obtained as a consequence of a previous priority inheritance.

Parameters:

task	The descriptor address of the affected task.
prio	The new task priority. This value must range from [0 .. 99] (inclusive) where 0 is the lowest effective priority.

Returns:: Upon success, the previously set priority is returned. Otherwise:

-EINVAL is returned if task is not a task descriptor, or if prio is invalid.

-EPERM is returned if task is NULL but not called from a task context.

-EIDRM is returned if task is a deleted task descriptor.

Side-effects:

This service calls the rescheduling procedure.

Assigning the same priority to a running or ready task moves it to the end of its priority group, thus causing a manual round-robin.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine only if task is non-NULL.

Kernel-based task
User-space task

Rescheduling: possible if task is the current one.

References xnpod_schedule(), and xnpod_set_thread_schedparam().

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

Turns the current Linux task into a native Xenomai task.

Creates a real-time task running in the context of the calling regular Linux task in user-space.

Parameters:

task In non-NULL, the address of a task descriptor Xenomai will use to store the task-related data; this descriptor must always be valid while the task is active therefore it must be allocated in permanent memory. If NULL is passed, then the descriptor will not be returned; main() threads which do not need to be referred to by other threads may use this syntax to promote themselves to the real-time domain for instance.

Note:: Allowing for a NULL descriptor pointer to be passed is a recent feature which is not available with any earlier Xenomai release.

The current context is switched to primary execution mode and returns immediately, unless T_SUSP has been passed in the mode parameter.

Parameters:

name	An ASCII string standing for the symbolic name of the task. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created task.
prio	The base priority which will be set for the current task. This value must range from [0 .. 99] (inclusive) where 0 is the lowest effective priority.
mode	The task creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new task:

T_FPU allows the task to use the FPU whenever available on the platform. This flag is forced for this call, therefore it can be omitted.

T_SUSP causes the task to enter the suspended mode after it has been put under Xenomai's control. In such a case, a call to rt_task_resume() will be needed to wake up the current task.

T_CPU(cpuid) makes the current task affine to CPU # cpuid. CPU identifiers range from 0 to RTHAL_NR_CPUS - 1 (inclusive). The calling task will migrate to another processor before this service returns if the current one is not part of the CPU affinity mask.

Passing T_CPU(0)|T_CPU(1) in the mode parameter thus defines a task affine to CPUs #0 and #1.

Returns:: 0 is returned upon success. Otherwise:

-EBUSY is returned if the current Linux task is already mapped to a Xenomai context.

-ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to create or register the task.

-EEXIST is returned if the name is already in use by some registered object.

-EPERM is returned if this service was called from an asynchronous context.

Environments:

This service can be called from:

User-space task (enters primary mode)

Rescheduling: possible.

Note:

When creating or shadowing a Xenomai thread for the first time in user-space, Xenomai installs a handler for the SIGWINCH signal. If you had installed a handler before that, it will be automatically called by Xenomai for SIGWINCH signals that it has not sent.

If, however, you install a signal handler for SIGWINCH after creating or shadowing the first Xenomai thread, you have to explicitly call the function xeno_sigwinch_handler at the beginning of your signal handler, using its return to know if the signal was in fact an internal signal of Xenomai (in which case it returns 1), or if you should handle the signal (in which case it returns 0). xeno_sigwinch_handler prototype is:

int xeno_sigwinch_handler(int sig, siginfo_t *si, void *ctxt);

Which means that you should register your handler with sigaction, using the SA_SIGINFO flag, and pass all the arguments you received to xeno_sigwinch_handler.

Examples:: rtcanrecv.c, and rtcansend.c.

References pthread_getspecific(), pthread_self(), pthread_setcanceltype(), and pthread_setspecific().

int rt_task_sleep ( RTIME delay )

Delay the calling task (relative).

Delay the execution of the calling task for a number of internal clock ticks.

Parameters:

delay The number of clock ticks to wait before resuming the task (see note). Passing zero causes the task to return immediately with no delay.

Returns:: 0 is returned upon success, otherwise:

-EINTR is returned if rt_task_unblock() has been called for the sleeping task before the sleep time has elapsed.

-EWOULDBLOCK is returned if the system timer is inactive.

-EPERM is returned if this service was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).

Environments:

This service can be called from:

Kernel-based task
User-space task (switches to primary mode)

Rescheduling: always unless a null delay is given.

Note:: The delay value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

References pthread_setcanceltype(), XNBREAK, XNDELAY, and xnpod_suspend_thread().

int rt_task_sleep_until ( RTIME date )

Delay the calling task (absolute).

Delay the execution of the calling task until a given date is reached.

Parameters:

date The absolute date in clock ticks to wait before resuming the task (see note). As a special case, TM_INFINITE is an acceptable value that makes the caller block indefinitely, until rt_task_unblock() is called against it. Otherwise, any wake up date in the past causes the task to return immediately with no delay.

Returns:: 0 is returned upon success. Otherwise:

-EINTR is returned if rt_task_unblock() has been called for the sleeping task before the sleep time has elapsed.

-ETIMEDOUT is returned if date has already elapsed.

-EWOULDBLOCK is returned if the system timer is inactive, and
Date:
is valid but different from TM_INFINITE.
-EPERM is returned if this service was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).

Environments:

This service can be called from:

Kernel-based task
User-space task (switches to primary mode)

Rescheduling: always unless a date in the past is given.

Note:: The date value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

References pthread_setcanceltype(), XNBREAK, XNDELAY, xnpod_suspend_thread(), and xntbase_get_time().

int rt_task_slice	(	RT_TASK *	task,
		RTIME	quantum
	)

Set a task's round-robin quantum.

Set the time credit allotted to a task undergoing the round-robin scheduling. If quantum is non-zero, rt_task_slice() also refills the current quantum for the target task, otherwise, time-slicing is stopped for that task.

Parameters:

task	The descriptor address of the affected task. If task is NULL, the current task is considered.
quantum	The round-robin quantum for the task expressed in ticks (see note).

Returns:: 0 is returned upon success. Otherwise:

-EINVAL is returned if task is not a task descriptor.

-EPERM is returned if task is NULL but not called from a task context.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine only if task is non-NULL.

Kernel-based task
User-space task

Rescheduling: never.

Note:: The quantum value is always interpreted as a count of ticks. If the task undergoes aperiodic timing, the tick duration is defined by CONFIG_XENO_OPT_TIMING_VIRTICK.

References xnpod_set_thread_tslice().

int rt_task_spawn	(	RT_TASK *	task,
		const char *	name,
		int	stksize,
		int	prio,
		int	mode,
		void()(void cookie)	entry,
		void *	cookie
	)		`[inline, static]`

Spawn a new real-time task.

Creates and immediately starts a real-time task, either running in a kernel module or in user-space depending on the caller's context. This service is a simple shorthand for rt_task_create() followed by a call to rt_task_start().

Parameters:

task	The address of a task descriptor Xenomai will use to store the task-related data. This descriptor must always be valid while the task is active therefore it must be allocated in permanent memory.
name	An ASCII string standing for the symbolic name of the task. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created task.
stksize	The size of the stack (in bytes) for the new task. If zero is passed, a reasonable pre-defined size will be substituted.
prio	The base priority of the new task. This value must range from [0 .. 99] (inclusive) where 0 is the lowest effective priority.
mode	The task creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new task:

T_FPU allows the task to use the FPU whenever available on the platform. This flag is forced for user-space tasks.

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 RTHAL_NR_CPUS - 1 (inclusive).

T_JOINABLE (user-space only) allows another task to wait on the termination of the new task. This implies that rt_task_join() is actually called for this task to clean up any user-space located 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.

Parameters:

entry	The address of the task's body routine. In other words, it is the task entry point.
cookie	A user-defined opaque cookie the real-time kernel will pass to the emerging task as the sole argument of its entry point.

Returns:: 0 is returned upon success. Otherwise:

-ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to create the new task's stack space or register the task.

-EEXIST is returned if the name is already in use by some registered object.

-EPERM is returned if this service was called from an asynchronous context.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: possible.

Note:

When creating or shadowing a Xenomai thread for the first time in user-space, Xenomai installs a handler for the SIGWINCH signal. If you had installed a handler before that, it will be automatically called by Xenomai for SIGWINCH signals that it has not sent.

If, however, you install a signal handler for SIGWINCH after creating or shadowing the first Xenomai thread, you have to explicitly call the function xeno_sigwinch_handler at the beginning of your signal handler, using its return to know if the signal was in fact an internal signal of Xenomai (in which case it returns 1), or if you should handle the signal (in which case it returns 0). xeno_sigwinch_handler prototype is:

int xeno_sigwinch_handler(int sig, siginfo_t *si, void *ctxt);

Which means that you should register your handler with sigaction, using the SA_SIGINFO flag, and pass all the arguments you received to xeno_sigwinch_handler.

References rt_task_create(), and rt_task_start().

int rt_task_start	(	RT_TASK *	task,
		void()(void cookie)	entry,
		void *	cookie
	)

Start a real-time task.

Start a (newly) created task, scheduling it for the first time. This call releases the target task from the dormant state.

The TSTART hooks are called on behalf of the calling context (if any, see rt_task_add_hook()).

Parameters:

task	The descriptor address of the affected task which must have been previously created by the rt_task_create() service.
entry	The address of the task's body routine. In other words, it is the task entry point.
cookie	A user-defined opaque cookie the real-time kernel will pass to the emerging task as the sole argument of its entry point.

Returns:: 0 is returned upon success. Otherwise:

-EINVAL is returned if task is not a task descriptor.

-EIDRM is returned if task is a deleted task descriptor.

-EBUSY is returned if task is already started.

-EPERM is returned if this service was called from an asynchronous context.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: possible.

References XNDORMANT, and xnpod_start_thread().

Referenced by rt_task_spawn().

int rt_task_suspend ( RT_TASK * task )

Suspend a real-time task.

Forcibly suspend the execution of a task. This task will not be eligible for scheduling until it is explicitly resumed by a call to rt_task_resume(). In other words, the suspended state caused by a call to rt_task_suspend() is cumulative with respect to the delayed and blocked states caused by other services, and is managed separately from them.

A nesting count is maintained so that rt_task_suspend() and rt_task_resume() must be used in pairs.

Receiving a Linux signal causes the suspended task to resume immediately.

Parameters:

task	The descriptor address of the affected task. If task is NULL, the current task is suspended.

Returns:: 0 is returned upon success. Otherwise:

-EINTR is returned if a Linux signal has been received by the suspended task.

-EINVAL is returned if task is not a task descriptor.

-EPERM is returned if this service was called from an invalid context (e.g. interrupt, non-realtime context).

-EIDRM is returned if task is a deleted task descriptor.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine only if task is non-NULL.

Kernel-based task
User-space task (switches to primary mode)

Rescheduling: always if task is NULL.

References XNBREAK, xnpod_suspend_thread(), and XNSUSP.

int rt_task_unbind ( RT_TASK * task ) [inline, static]

Unbind from a real-time task.

This user-space only service unbinds the calling task from the task object previously retrieved by a call to rt_task_bind().

Parameters:

task	The address of a task descriptor to unbind from.

Returns:: 0 is always returned.

This service can be called from:

User-space task.

Rescheduling: never.

int rt_task_unblock ( RT_TASK * task )

Unblock a real-time task.

Break the task out of any wait it is currently in. This call clears all delay and/or resource wait condition for the target task. However, rt_task_unblock() does not resume a task which has been forcibly suspended by a previous call to rt_task_suspend(). If all suspensive conditions are gone, the task becomes eligible anew for scheduling.

Parameters:

task	The descriptor address of the affected task.

Returns:: 0 is returned upon success. Otherwise:

-EINVAL is returned if task is not a task descriptor.

-EIDRM is returned if task is a deleted task descriptor.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine
Kernel-based task
User-space task

Rescheduling: possible.

References xnpod_schedule(), and xnpod_unblock_thread().

int rt_task_wait_period ( unsigned long * overruns_r )

Wait for the next periodic release point.

Make the current task wait for the next periodic release point in the processor time line.

Parameters:

overruns_r If non-NULL, overruns_r must be a pointer to a memory location which will be written with the count of pending overruns. This value is copied only when rt_task_wait_period() returns -ETIMEDOUT or success; the memory location remains unmodified otherwise. If NULL, this count will never be copied back.

Returns:: 0 is returned upon success; if overruns_r is valid, zero is copied to the pointed memory location. Otherwise:

-EWOULDBLOCK is returned if rt_task_set_periodic() has not previously been called for the calling task.

-EINTR is returned if rt_task_unblock() has been called for the waiting task before the next periodic release point has been reached. In this case, the overrun counter is reset too.

-ETIMEDOUT is returned if a timer overrun occurred, which indicates that a previous release point has been missed by the calling task. If overruns_r is valid, the count of pending overruns is copied to the pointed memory location.

-EPERM is returned if this service was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).

Environments:

This service can be called from:

Kernel-based task
User-space task (switches to primary mode)

Rescheduling: always, unless the current release point has already been reached. In the latter case, the current task immediately returns from this service without being delayed.

References pthread_setcanceltype(), and xnpod_wait_thread_period().

int rt_task_yield ( void )

Manual round-robin.

Move the current task to the end of its priority group, so that the next equal-priority task in ready state is switched in.

Returns:: 0 is returned upon success. Otherwise:

-EPERM is returned if this service was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).

Environments:

This service can be called from:

Kernel-based task
User-space task

Rescheduling: always if a next equal-priority task is ready to run, otherwise, this service leads to a no-op.

Files

Functions

Detailed Description

Function Documentation