TBD.h File Reference
Task Block of Data manager, function prototypes and public data structures.
More...
|
Functions |
int | TBD_initialize (void) |
| One time TBD system initialization call.
|
int | TBD_add (TBD_ctl *tbd) |
| Estblishes a pointer to the task specific TBD control structure.
|
int | TBD_delete (void) |
| Deletes the association a pointer to the task specific TBD control structure.
|
int | TBD_destroy (void) |
| Shutdown the TBD facility.
|
void * | TBD_get (void **tbd, int index) |
| Returns the value task global data at the specified index.
|
void | TBD_put (void **tbd, int index, void *value) |
| Puts the data value into the task specific data area at the specified index.
|
void ** | TBD_locate (void) |
| Locates the block of task data.
|
void ** | TBD_glocate (void) |
| Locates the block of task data.
|
Detailed Description
Task Block of Data manager, function prototypes and public data structures.
- Author:
- JJRussell - russell@slac.stanford.edu
CVS $Id: TBD.h,v 1.3 2004/12/07 16:13:05 russell Exp $
Function Documentation
int TBD_add |
( |
TBD_ctl * |
tbd |
) |
|
Estblishes a pointer to the task specific TBD control structure.
- Parameters:
-
| tbd | Pointer to the TBD control structure for this TASK. |
- Returns:
- Status
This routine is generally called once at task initialization time to establish a pointer to the TBD control structure for the calling task. When using tasks created by the TASK facility in PBS, this call is made automatically.
Deletes the association a pointer to the task specific TBD control structure.
- Returns:
- Status
This routine is generally called once at
task exit time to dissolve the association of the pointer to the TBD control structure with the calling task. Note that freeing the memory of the managed area is the user's responsibility.
When using tasks created by the TASK facility in PBS, this call is made automatically at task exit. The memory of the managed area is also freed.
Shutdown the TBD facility.
- Returns:
- Status
This routine is generally called once at
system exit time to remove the global pointer (key).
Referenced by PBS_shutdown().
void * TBD_get |
( |
void ** |
tbd, |
|
|
int |
index | |
|
) |
| | |
Returns the value task global data at the specified index.
- Parameters:
-
| tbd | The table location, from a call to TBD_locate() or one of its cousins. |
| index | The index of the requested data value. |
- Returns:
- The data value at the specified index.
The implementation of this function is very efficient of the VXWORKS platform, requiring approximately 3 instructions. It is highly recommended that the inline form of this function be used.
- Warning:
- If you have any doubt the TBD facility has not been initialized for the task you a making the call in, make sure to check the value returned from TBD_locate() or one of its cousins for NULL before calling TBD_get().
void ** TBD_glocate |
( |
void |
|
) |
|
Locates the block of task data.
- Returns:
- Handle of the managed data area or NULL if called from a task that did not establish a managed data area.
This call is similar to
TBD_locate(), but, if called in ISR context, returns a handle to the ISR specfic managed data area. Because the implementation of this function on VxWork's platforms is only in the 6-8 instruction area, the user is encouraged to use the inline version of this routine.
- Warning:
- While this function will return non-NULL in an ISR context, it still may return a NULL handle if called from a task that has not established a task specific managed data area.
If you have any doubts about whether the calling context has a managed area associated with it, make sure to check this handle being non-NULL before using it. If the caller knows that the calling context is always at task level, the TBD_locate is more efficient.
See TBD_locate() for a usage example.
int TBD_initialize |
( |
void |
|
) |
|
One time TBD system initialization call.
- Returns:
- Status
This is not part of the runtime interface, but the documentation is provided for completeness. While the implementation of this routine is platform dependent, generally speaking, this routine establishes the address of the TBD maintained data structure as a task specific piece of data. The underlying OS then ensures that a pointer to the calling task's TBD data structure is made available.
Referenced by PBS_initialize2().
void ** TBD_locate |
( |
void |
|
) |
|
Locates the block of task data.
- Returns:
- Handle of the managed data area or NULL if called from a task that did not establish a managed data area or if called from an ISR (interrupt level).
This function returns a handle to the managed area for the current task. This handle is passed to
TBD_put() and
TBD_get() to perform reads and writes to selected locations.
The implementation of this function is very efficient of the VXWORKS platform, requiring approximately 2 instructions. It is highly recommended that the inline form of this function be used.
- Warning:
- If you have any doubts about whether the calling context has a managed area associated with it, make sure to check this handle being non-NULL before using it. If desired, one may use TBD__glocate(), which will return a handle to a ISR specific data area. If, however, the caller knows the call is being made in the context of a task, TBD_locate() is more efficient.
EXAMPLE
-------
void **tbd = TBD__locate ();
/ * Check for NULL * /
if (tbd != NULL)
{
int org_1 = TBD__get (tbd, DATA_IDX_1);
int org_2 = TBD__get (tbd, DATA_IDX_2];
TBD__put (tbd, DATA_IDX_1, 0xdeadbeef);
TBD__put (tbd, DATA_IDX_2, 0xabadcafe);
}
void TBD_put |
( |
void ** |
tbd, |
|
|
int |
index, |
|
|
void * |
value | |
|
) |
| | |
Puts the data value into the task specific data area at the specified index.
- Parameters:
-
| tbd | The table location, from a call to TBD_locate () |
| index | The index of the target data word |
| value | The value to put into the target data word |
Puts (writes)
value into the task specific data area at the specified
index.
The implementation of this function is very efficient of the VXWORKS platform, requiring approximately 3 instructions. It is highly recommended that the inline form of this function be used.