GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > PBS / V2-10-5

Constituent: pbs     Tag: rad750


Interface   Data Structures   File List   Data Fields   Globals  

TBD.c File Reference

Task Block of Data manager, callable implementation, common platform. More...

#include <string.h>
#include "PBS/TBD.h"
#include "TBD_pvtdefs.h"

Include dependency graph for TBD.c:

Include dependency graph

Detailed Description

Task Block of Data manager, callable implementation, common platform.

Author:
JJRussell - russell@slac.stanford.edu

    CVS $Id: TBD.c,v 1.4 2004/12/07 16:13:11 russell Exp $

SYNOPSIS
TBD manages an array of N (likely 32) words that act as global, but task specific, variables. The real value of this block is that no context handle is needed to locate them. TBD acts as a green layer between the POSIX and VXWORKS implementations, although, as always in PBS, the implementation is tilted towards efficiency on the VXWORKS platform.
Under POSIX, the address of the data area is associated with a task dependent key. The OS is responsible for making sure that the key is updated across task switches. Accesses to the maintained data array cost a pthread function call to translate the key to the data array address.

Under VXWORKS, the address of a location holding a pointer to the data area is made known to the OS. VXWORKS is responsible for making sure that this location is updated across task switches. Because the address of the data location is stored in a well-known external variable, no special routines are needed to reference the address. However, to ensure portability, TBD provides access routines in the form of inline functions. See the usage section for details.

USAGE
The user need provide no TBD specific initialization beyond establishing the value of his parameter. The TBD default is to initialize the data cell word with 0. The user interface consists of #- TBD_locate(), to locate the storage array #- TBD_get (), to get a value from the storage array #- TBD_put (), to put a value into the storage array
The user calls TBD_locate() to locate the address of the managed area. TBD_locate will return a non-NULL result only to tasks that have handed the TBD facility an area to manage by doing a TBD_add(). TBD_locate will return NULL not only from tasks not calling TBD_add, but also if it is called from ISR (interrupt) level. As a convenience, the TBD facility also maintains one context block to be used to store context at interrupt level. Because there is extra overhead associated with using this feature, a separate call, TBD_glocate() (generalized locate) should be used if the caller wishes to make use of this feature. Note the TBD_glocate() will still return NULL for tasks that have not done a TBD_add()

Once a task has added a block of memory to be managed (the TASK routines do this call as a convenience), the rest of the code generally does accesses by calling TBD_locate() or TBD_glocate(). After checking that this pointer is non-NULL, the caller accesses the managed data area by calling TBD_put() for writes and TBD_get() for reads. Although a traditional call interface is provided for each routine, the user is encouraged to use the inline versions. Under VxWorks, the inlines are in the 3-6 instruction area.

EXAMPLE
Here are is an example of implementing a read and replace function. Note that this is not an interlocked version of the routine. It also uses the traditional callable functions. The inlines are the recommended form.
       static inline void *replace (int index, void *value)
       {
          void **tbd = TBD_locate ();
          void  *org = TBD_get (tbd, index);

          TBD_put (tbd, index, value);
          return org;
       }

Generated on Tue Sep 13 21:46:52 2005 by doxygen 1.3.3