Task Signal API
[Task Synchronization API]


Files

file  task_signal.h
 [host] MARS Task Signal API
file  task_signal.h
 [MPU] MARS Task Signal API

Functions

int mars_task_signal_send (struct mars_task_id *id)
 [host/MPU] Sends a signal to the specified task.
int mars_task_signal_wait (void)
 [MPU] Waits and yields caller task until receiving signal. (Task Switch Call)
int mars_task_signal_try_wait (void)
 [MPU] Waits for task until receiving signal.

Detailed Description

The MARS task signal is the simplest form of synchronization between a host program and multiple MARS tasks.

From either a host program or MARS task you can specify a certain task to signal. When the task waits for a signal to be received it will be transitioned to the waiting state until the signal is received.


Function Documentation

int mars_task_signal_send ( struct mars_task_id id  ) 

[host/MPU] Sends a signal to the specified task.

This function sends a signal to the task specified. If the task had previously called mars_task_signal_wait and was in the waiting state, this function will cause that task to switch to a ready state and scheduled to run accordingly. If the task has not yet called mars_task_signal_wait, the tasks's signal buffer will be set and the same order of events will occur as previously explained once mars_task_signal_wait is called. The task signal buffer depth is 1. Therefore if the signal buffer is already set when a another signal is received, it has no effect.

Parameters:
[in] id - pointer to task id of task to signal
Returns:
MARS_SUCCESS - successfully yielded task
MARS_ERROR_NULL - null pointer specified
MARS_ERROR_PARAMS - bad task id specified
MARS_ERROR_STATE - task is in an invalid state

int mars_task_signal_wait ( void   ) 

[MPU] Waits and yields caller task until receiving signal. (Task Switch Call)

Note:
The [MPU] call may result in a task switch and put this task into the waiting state. Understand all the limitations before calling a Task Switch Call (See 7.5 Task Switching).
This function will cause the task to enter a waiting state until some other entity calls mars_task_signal_send to this task to return it to the ready state. The task will not be scheduled to run until it receives the signal and returned to the ready state. Once the task receives the signal and this function returns MARS_SUCCESS, the signal buffer is cleared.

Returns:
MARS_SUCCESS - successfully yielded task
MARS_ERROR_FORMAT - no context save area specified

int mars_task_signal_try_wait ( void   ) 

[MPU] Waits for task until receiving signal.

This function will check the state of a task to see if some other entity has called mars_task_signal_send to this task and returns immediately with the result. Once the task receives the signal and this function returns MARS_SUCCESS, the signal buffer is cleared.

Returns:
MARS_SUCCESS - successfully yielded task
MARS_ERROR_BUSY - signal not yet received


Generated on Wed Jan 13 04:46:22 2010 for MARS by  doxygen 1.5.7.1