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