GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> IPBS / V0-0-2 > pbs / i845e
#include <IPBS/TOV.h>
Classes | |
struct | _TASK_attr |
Encapsulates the more esoteric options. More... | |
Defines | |
#define | TASK_PRINTF(_args) |
Debugging macro acting as a stand in for printf. | |
#define | TASK_K_NAME_MAX 16 |
The maximum size of a task's name, including the terminating NUL character. | |
Typedefs | |
typedef struct _TASK_attr | TASK_attr |
Typedef for struct _TASK_attr. | |
typedef enum _TASK_priority_type | TASK_priority_type |
Typedef for enum _TASK_priority_type. | |
typedef void * | TASK_parameter |
The type of the parameter passed to the task's entry point routine. | |
typedef void *(* | TASK_entry )(TASK_parameter parameter) |
The function signature of the task's entry point routine. | |
typedef struct _TASK_tcb | TASK_tcb |
TASK facility's definition of a Task Control Block. | |
typedef int(* | TASK_block_cb )(void *prm) |
Callback routine of TASK_block. | |
Enumerations | |
enum | _TASK_priority_type { TASK_K_PRIORITY_TYPE_ABS = 0, TASK_K_PRIORITY_TYPE_REL = 1 } |
Indicates how a priority specification to TASK_attr_setpriority is interpretted. More... | |
Functions | |
int | TASK_attr_init (TASK_attr *attributes) |
Provides a standard method of initializing the attributes block to a set of known values. These values may be platform dependent. | |
int | TASK_attr_priority_set (TASK_attr *attributes, int priority) |
Sets the priority field in the task attributes block to the the specified value. This can be either absolute or relative to the current task's priority. | |
int | TASK_activate (TASK_tcb *tcb) |
Activates a previously created task. | |
int | TASK_create (TASK_tcb *tcb, const TASK_attr *attributes, TASK_entry entry_point, TASK_parameter parameter) |
Creates, but does not activate a task. | |
int | TASK_convert (TASK_tcb *tcb, const TASK_attr *attributes, TASK_entry entry_point, TASK_parameter parameter) |
Converts an existing VxWorks task to a TASK. | |
int | TASK_spawn (TASK_tcb *tcb, const TASK_attr *attributes, TASK_entry entry_point, TASK_parameter parameter) |
Convenience routine to both create and activate a task. | |
int | TASK_destroy (TASK_tcb *tcb) |
Destroys, ie deletes, a previously created task. | |
void | TASK_exit (void *status) |
Causes the calling task to delete itself and allows notification to another task, via TASK_join() that the calling task has deleted itself. | |
int | TASK_join (TASK_tcb *tcb, void **status) |
Blocks the calling task until the specified task completes. | |
int | TASK_revert (TASK_tcb *tcb) |
Strips a task/thread of its TASK functionality. | |
TASK_tcb * | TASK_cvt (void) |
Converts an existing VXWORKs task or POSIX thread to TASK object. | |
int | TASK_rvt (void) |
Reverts the current task back to its native self by stripping it of its TASK functionality. | |
int | TASK_pause (unsigned int nsecs) |
Causes the calling task to wait (pause) for the specified number of nanoseconds. | |
int | TASK_resume (TASK_tcb *tcb) |
Resumes a previously suspended task. | |
int | TASK_suspend (TASK_tcb *tcb) |
Suspends a task. | |
int | TASK_wait (const TOV tov) |
Causes the calling task to wait (pause) until the specified timeout is reached. | |
int | TASK_block (TASK_block_handle *tbh, TASK_block_cb rtn, void *prm) |
Provides a simple way to turn an asynchronous routine into a synchronous routine. | |
int | TASK_unblock (TASK_block_handle tbh) |
Unblocks a task blocked on a call to TASK_block. | |
int | TASK_priority_get (const TASK_tcb *tcb) |
Gets the current priority of the specified task. The priority is returned expressed in the native tasking model's scheme. | |
int | TASK_tcb_sizeof (void) |
Returns the size, in bytes, of a TCB to be used when creating or spawning a TASK. | |
int | TASK_xtcb_sizeof (void) |
Returns the size, in bytes, of a TCB to be used when converting an existing (platform native task) to a TASK type task. | |
TASK_tcb * | TASK_self (void) |
Returns the tcb of the calling task. | |
const char * | TASK_name (const TASK_tcb *tcb) |
Returns a pointer to the task's name. | |
int | TASK_priority_number_boost (int priority, int boost) |
Boosts the priority number by the boost. | |
int | TASK_priority_number_compute (int priority, TASK_priority_type type, const TASK_tcb *tcb) |
Computes a priority number, either as an absolute or based on the priority of another task. | |
int | TASK_priority_number_limit (int priority) |
Limits the priority number to fit within the specified bounds. | |
int | TASK_priority_set (TASK_tcb *tcb, int priority) |
Sets priority of the specified task to the specified value. |
CVS $Id: TASK.h,v 1.2 2011/03/25 21:15:02 saxton Exp $
Another way would be to map some restricted range of the VxWorks set (say 0-98) to the POSIX range. This is better but suffers from another problem. Some VxWorks layered products start tasks that run at very specific priorities, for example, the Network task when running with a TCP/IP stack. The user must be careful to correctly position his task's priority relative to these tasks. Restricting the range VxWork's range could impair this ability.
Another possibility is to map the POSIX set to the VxWorks set. One would always specify priorities in the POSIX scheme. This would avoid the problem of mapping two different priorities to the identical priorities. The cost of this would be to restrict the VxWorks priority set to 100 different priorities. This might be acceptable, but runs counter to the PBS philosophy of providing a portable set of routines biased towards the VxWorks implementation.
In the end, there is really no good way to merge these two different schemes. The compromise is that absolute priorities are deemed to be not a portable concept. If the user chooses to use absolute priorities, it is up to him to layer this out. The TASK routines will, however, support the concept of RAISING and LOWERING priorities by a fixed delta. The only restriction is that the resulting priority must lie within the implementations acceptable range. Note that RAISING and LOWERING always means a task with a higher priority runs before a task of lower priority. In the VxWorks implementation RAISING the priority results in lowering the task's priority number. (God, this is confusing.)
Two sets of limits are given
Symbol Meaning VxWorks POSIX TASK_K_PRIORITY_MIN Minimum task priority number 0 1 TASK_K_PRIORITY_MAX Maximum task priority number 255 99 TASK_K_PRIORITY_LO Lowest task priority number 255 1 TASK_K_PRIORITY_HI Highest task priority number 0 99
The first set is useful for limit checking, i.e. making sure a given priority is acceptable on that platform. The second set allows one to implement a relative mapping scheme.
#define TASK_K_NAME_MAX 16 |
The maximum size of a task's name, including the terminating NUL character.
This quantity is defined for portability reasons. One some platforms, there is no maximum size, but, given that the only value of the name is for display purposes, it makes it easier to write displays if the name is limited to some reasonable number of characters. So, the request is that the user's of TASK limit the task names to this value independent of whether the underlying OS supports more or not. Note, however, that the TASK facility does not enforce this policy.
#define TASK_PRINTF | ( | _args | ) |
Debugging macro acting as a stand in for printf.
_args | A parenthesis inclosed set of arguments to printf |
Typedef for struct _TASK_attr.
This data structure allows the caller to fine tune the task creation parameters in a semi-portable fashion. Not all fields are supported on all platforms.
int(* TASK_block_cb)(void *prm) |
Callback routine of TASK_block.
A | user parameter passed to the callback routine |
The function signature of the task's entry point routine.
This is the function signature of the task's entry point routine. It is as simple as one can make it, i.e.
void *exit_parameter = (*entry_point) (TASK_parameter parameter);
The TASK_parameter is just a void *, but is typedef'd so that the code documents neatly.
The type of the parameter passed to the task's entry point routine.
This type is just a void *, but is typedef'd so that the code documents neatly.
Typedef for enum _TASK_priority_type.
Indicates how a priority specification to TASK_attr_setpriority is interpretted. This can be either as an absolute or as a signed number relative to the another task's priority.
TASK facility's definition of a Task Control Block.
Typedef for struct _TASK_tcb.
The user should never manipulate this data structure directly. It is provided only so the compiler can lay down storage. Direct manipulation will kill the portability of the code since the exact contents are platform dependent.
The TASK_tcb may include the native VxWorks TCB and is augmented by additional fields which make the TASK interface portable across VxWork's and POSIX implementations. The VxWorks TCB is only included when TASK_create() or TASK_spawn() is used. Existing VxWorks may be converted to have TASK functionality by a call to TASK_convert(). In this case the VxWorks TCB already exists.
enum _TASK_priority_type |
int TASK_activate | ( | TASK_tcb * | tcb | ) |
Activates a previously created task.
tcb | The task control block of the task to activate. |
References _TASK_tcb::tid.
Referenced by TASK_spawn().
int TASK_attr_init | ( | TASK_attr * | attributes | ) |
Provides a standard method of initializing the attributes block to a set of known values. These values may be platform dependent.
attributes | The attributes block to initialize |
References _TASK_attr::name, _TASK_attr::options, _TASK_attr::priority, _TASK_attr::stack_addr, and _TASK_attr::stack_size.
int TASK_attr_priority_set | ( | TASK_attr * | attributes, | |
int | priority | |||
) |
Sets the priority field in the task attributes block to the the specified value. This can be either absolute or relative to the current task's priority.
attributes | The target attributes block | |
priority | A signed integer indicating the absolute or relative priority. |
References _TASK_attr::priority, and TASK__priority_number_limit().
int TASK_block | ( | TASK_block_handle * | tbh, | |
TASK_block_cb | rtn, | |||
void * | prm | |||
) |
Provides a simple way to turn an asynchronous routine into a synchronous routine.
tbh | Pointer to a location to hold the task blocking handle This is must be passed to TASK_unblock to unblock the TASK upon completion of the routine. | |
rtn | The asynchronous callback routine to execute | |
prm | A parameter to be passed to the above routine. |
struct Synch { TASK_block_handle tbh; char buf[100]; void nbytes; SynchRtn synch_rtn; } synch; synch->synch_rtn = read_synch; status = TASK_block (&synch->tbh, read_it, &synch);
int read_synch (Synch *synch) { return TASK_unblock (synch->tbh); }
int TASK_convert | ( | TASK_tcb * | tcb, | |
const TASK_attr * | attributes, | |||
TASK_entry | entry_point, | |||
TASK_parameter | parameter | |||
) |
Converts an existing VxWorks task to a TASK.
tcb | The task control block to initialize | |
attributes | The task attributes block. This may be NULL, in which case the system defaults are used. | |
entry_point | The task's new entry point address. If this is non-NULL this will act as a user callback routine with the flow of control being passed onto this routine with parameter being passed to this routine. If NULL, control will pass back to the caller. | |
parameter | A parameter passed transparently to the entry_point routine. |
TASK_resume (), etc.
nbytes = TASK_xtcb_sizeof (); // Get the size of a conversion block tcb = MBA_alloc (nbytes); // Allocate memory for it // Give control to TASK, it will just call (*myRoutine)(myParameter) // then return when that routine is down status = TASK_convert (tcb, NULL, myRoutine, myParameter); // Strip this task of TASK functionality status = TASK_revert (tcb); // Return the TASK resources MBA_free (tcb); // Free the memory for the tcb
The second usage is when doing informal coding in the shell.
nbytes = TASK_xtcb_sizeof (); // Get the size of a conversion block tcb = MBA_alloc (nbytes); // Allocate memory for it // Just create and initialize the tcb status = TASK_convert (tcb, NULL, NULL, NULL); ... lots of code // Strip this task of TASK functionality status = TASK_revert (tcb); // Return the TASK resources MBA_free (tcb); // Free the memory for the tcb
Naturally the above example (the one without the user callback routine can be used in the other case also, but, style-wise, usage of the calback is structurally cleaner.
TASK_rvt(). TASK_cvt combines the sizing and memory allocation with TASK_convert(), while, at least currently TASK_rvt() returns the memory and calls TASK_revert(). The rule is always pair TASK_convert/TASK_revert or TASK_cvt/TASK_rvt
References _TASK_tcb::pcb, _TASK_attr::priority, TASK_priority_set(), and _TASK_tcb::tid.
Referenced by TASK_cvt().
int TASK_create | ( | TASK_tcb * | tcb, | |
const TASK_attr * | attributes, | |||
TASK_entry | entry_point, | |||
TASK_parameter | parameter | |||
) |
Creates, but does not activate a task.
tcb | The task control block of the task to create | |
attributes | A collection of attributes used to exactly specify the task. This parameter may be specified as NULL. In this case, a platform dependent set of attributes is assigned. | |
entry_point | The address of the entry point of the newly created task. See TASK_entry for the call signature. | |
parameter | A parameter which is passed transparently to the newly created task's entry point. |
References _TASK_tcb::ecb, MBA_alloc(), _TASK_attr::name, _TASK_attr::options, _TASK_attr::priority, _TASK_ecb::semaphore, _TASK_ecb::stack, _TASK_attr::stack_addr, _TASK_attr::stack_size, task_entry_safe(), task_entry_unsafe(), TASK_K_STACK_SIZE_DEFAULT, TASK_K_STACK_SIZE_MINIMUM, TASK_M_OPTIONS_DETACH, _TASK_tcb::tid, and _TASK_ecb::value.
Referenced by TASK_spawn().
TASK_tcb * TASK_cvt | ( | void | ) |
Converts an existing VXWORKs task or POSIX thread to TASK object.
TASK_revert ().
References MBA_alloc(), MBA_free(), TASK_convert(), and TASK_xtcb_sizeof().
int TASK_destroy | ( | TASK_tcb * | tcb | ) |
Destroys, ie deletes, a previously created task.
tcb | The task control block of the task to destroy. |
References _TASK_tcb::tid.
int TASK_exit | ( | void * | exit_value | ) |
Causes the calling task to delete itself and allows notification to another task, via TASK_join() that the calling task has deleted itself.
exit_value | An arbitrary 32-bit value passed to TASK_join(). |
Note that the status value is a void *, so a pointer to any piece of information can be supplied with the usual caveat that the memory the pointer is aimed at remains valid until read.
References _TASK_tcb::ecb, _TASK_ecb::semaphore, TASK__self(), and _TASK_ecb::value.
Referenced by task_entry_safe().
int TASK_join | ( | TASK_tcb * | tcb, | |
void ** | exit_value | |||
) |
Blocks the calling task until the specified task completes.
tcb | The task to join | |
exit_value | Location to receive the exiting task's completion value. |
References _TASK_tcb::ecb, MBA_free(), _TASK_ecb::semaphore, _TASK_ecb::stack, _TASK_tcb::tid, and _TASK_ecb::value.
Referenced by FORK_join().
const char * TASK_name | ( | const TASK_tcb * | tcb | ) |
Returns a pointer to the task's name.
tcb | The tcb of the task |
ISR>,of | tcb is specified as NULL, but in interrupt context | |
UND>,if | tcb is non-NULL and not in interrupt context but no name is associated with the task. |
References _TASK_tcb::tid.
int TASK_pause | ( | unsigned int | nsecs | ) |
Causes the calling task to wait (pause) for the specified number of nanoseconds.
nsecs | The number of nanoseconds to pause. |
References TASK_wait(), and TOV_from_nsecs().
int TASK_priority_get | ( | const TASK_tcb * | tcb | ) |
Gets the current priority of the specified task. The priority is returned expressed in the native tasking model's scheme.
tcb | The task control block of which task to query. If specified as NULL, the current task's priority. |
References _TASK_tcb::tid.
Referenced by TASK_priority_number_compute().
int TASK_priority_number_boost | ( | int | priority, | |
int | boost | |||
) |
Boosts the priority number by the boost.
priority | The priority number to boost | |
boost | The amount to boost the priority number |
TASK_K_PRIORITY_MAX allowed priority numbers.
The boost can be specified as a positive or negative number. Positive boosts will always result in a priority number that raises a task's absolute priority. Negative numbers will always result in a priority number that lowers a task's priority number.
In all cases the routine will limit the resulting priority between the minimum,
TASK_K_PRIORITY_MAX numbers.
int TASK_priority_number_compute | ( | int | priority, | |
TASK_priority_type | type, | |||
const TASK_tcb * | tcb | |||
) |
Computes a priority number, either as an absolute or based on the priority of another task.
priority | If the type is specified as an absolute priority number, then this number is used as is. If the type is relative, then it is a signed number. Positive numbers are interpretted as raising the priority level (even though the value of the priority number itself may be decremented) whereas negative numbers are interpreted as lowering the priority level (even though the value of the priority number itself may be incremented.) | |
type | The type or manner in which to set the priority. This can be either relative or absolulte. | |
tcb | The task control block of a reference task. This is used iff type == TASK_K_PRIORITY_TYPE_REL. If specified as NULL, then the priority of the calling task is used. |
References TASK__priority_number_boost(), TASK__priority_number_limit(), TASK_K_PRIORITY_TYPE_REL, and TASK_priority_get().
int TASK_priority_number_limit | ( | int | priority | ) |
Limits the priority number to fit within the specified bounds.
priority | The priority number to limit. |
int TASK_priority_set | ( | TASK_tcb * | tcb, | |
int | priority | |||
) |
Sets priority of the specified task to the specified value.
tcb | The Task Control Block of the task to change the priority. If NULL, then the current task. | |
priority | The priority to set the task to. |
References _TASK_tcb::tid.
Referenced by TASK_convert().
int TASK_resume | ( | TASK_tcb * | tcb | ) |
Resumes a previously suspended task.
tcb | The Task Control Block of the task to resume |
References _TASK_tcb::tid.
Referenced by FORK_resume().
int TASK_revert | ( | TASK_tcb * | tcb | ) |
Strips a task/thread of its TASK functionality.
tcb | The Task Control Block. This may be NULL, in which case the current task is reverted. |
Although this call can be used with TASK_create() and TASK_spawn(), it is most usually called after TASK_convert().
References _TASK_tcb::pcb, TASK_self(), and _TASK_tcb::tid.
Referenced by TASK_rvt().
int TASK_rvt | ( | void | ) |
Reverts the current task back to its native self by stripping it of its TASK functionality.
TASK_revert (). This function should be used with its partner,
References MBA_free(), TASK_revert(), and TASK_self().
TASK_tcb * TASK_self | ( | void | ) |
Returns the tcb of the calling task.
Referenced by TASK_revert(), and TASK_rvt().
int TASK_spawn | ( | TASK_tcb * | tcb, | |
const TASK_attr * | attributes, | |||
TASK_entry | entry_point, | |||
TASK_parameter | parameter | |||
) |
Convenience routine to both create and activate a task.
tcb | The task control block of the task to spawn | |
attributes | A collection of attributes used to exactly specify the task. This parameter may be specified as NULL. In this case, a platform dependent set of attributes is assigned. | |
entry_point | The address of the entry point of the newly created task. See TASK_entry for the call signature. | |
parameter | A parameter which is passed transparently to the newly created task's entry point. |
References TASK_activate(), and TASK_create().
Referenced by FORK_create().
int TASK_suspend | ( | TASK_tcb * | tcb | ) |
Suspends a task.
tcb | The Task Control Block of the task to suspend |
References _TASK_tcb::tid.
Referenced by FORK_suspend().
TASK_tcb_sizeof | ( | void | ) |
Returns the size, in bytes, of a TCB to be used when creating or spawning a TASK.
Referenced by FORK_create(), and FORK_fcb_sizeof().
int TASK_unblock | ( | TASK_block_handle | tbh | ) |
Unblocks a task blocked on a call to TASK_block.
tbh | The task blocking handle |
int TASK_wait | ( | const TOV | tov | ) |
Causes the calling task to wait (pause) until the specified timeout is reached.
tov | The timeout value to wait until |
References _WUT_tmr::state, task_wakeup(), WUT_cancel(), WUT_INIT, WUT_K_EXPIRED, WUT_K_QUEUED, and WUT_start().
Referenced by TASK_pause().
TASK_xtcb_sizeof | ( | void | ) |
Returns the size, in bytes, of a TCB to be used when converting an existing (platform native task) to a TASK type task.
Referenced by TASK_cvt().