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

Constituent: pbs     Tag: rad750

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » SVC » source » PBS » V2-10-10 » src » impl

TASK.c.vx-xxx-xxx File Reference

The VxWorks implementation of the TASK utilities. More...

#include <semLib.h>
#include <intLib.h>
#include <taskHookLib.h>
#include "PBS/MBA.h"
#include "PBS/WUT.h"
#include "PBS/WUT_tmr.h"

Include dependency graph for TASK.c.vx-xxx-xxx:


Defines

#define TASK_K_DEFAULT_STACK_SIZE   20000
 Sets the stack size if the user does not explicitly declare one.

Functions

static void task_create_hook (WIND_TCB *tcb)
 Performs additional per task creation functions.
static void task_delete_hook (WIND_TCB *tcb)
 Performs per task deletion functions.
static void task_entry_safe (int options, TASK_entry usr_entry, TASK_parameter usr_parameter, TASK_tcb *tcb)
 Task entry point when the task is being started in a task delete safe fashion.
static void task_entry_unsafe (int options, TASK_entry usr_entry, TASK_parameter usr_parameter, TASK_tcb *tcb)
 Task entry point when the task is being started in a task delete unsafe fashion.
static WUT_cb_status task_wakeup (void *semaphore, WUT_tmr *tmr)
 Timer callback routine used in implementing TASK_wait.
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 ()
 Returns the size, in bytes, of a TCB to be used when converting an existing (platform native task) to a TASK type task.
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_revert (TASK_tcb *tcb)
 Strips a task/thread of its TASK functionality.
void 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.
int TASK_join (TASK_tcb *tcb, void **exit_value)
 Blocks the calling task until the specified task completes.
const char * TASK_name (const TASK_tcb *tcb)
 Returns a pointer to the task's name.
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_destroy (TASK_tcb *tcb)
 Destroys, ie deletes, a previously created 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_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_priority_set (TASK_tcb *tcb, int priority)
 Sets priority of the specified task to the specified value.
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_sys_init (void)
 Performs one time only initialization of the TASK facility.
int TASK_sys_shutdown (void)
 Performs the shutdown of the TASK facility. This essentially undoes what TASK_sys_init did.

Detailed Description

The VxWorks implementation of the TASK utilities.

Author:
JJRussell - russell@slac.stanford.edu
   CVS $Id: TASK.c.vx-xxx-xxx,v 1.8 2004/12/07 16:13:13 russell Exp $

Function Documentation

int TASK_activate (  TASK_tcb *  tcb  ) 
 

Activates a previously created task.

Parameters:
tcb The task control block of the task to activate.
Returns:
Status
Activates a previously created task. This allows the user to cleanly separate the definition, ie filling in the TASK_attr block, the task creation, using TASK_create(), and from the task activation.

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.

Returns:
Status of the task blocking callback routine
Parameters:
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.
Example
In this example an asynchronous routine, read_it, is executed in a synchronous manner. The first code block illustrates the TASK_block call.
      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);

This illustrates the TASK_unblock call
        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.

Returns:
Status
Parameters:
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.
For consistency, the calling sequence is the same as TASK_create(), however certain differences exist. The differences are mainly in the attributes block. The disposition of the attributes block is

  • name : Ignored. This differs from the pthreads version where the name can be assigned at task conversion time.
  • priority : If non-negative, the priority of the converted task will be changed to this value
  • options : Ignored
  • stack_addr: Ignored
  • stack_size: Ignored.

Usage
There are two typical uses of this routine, both allowing the caller to add TASK features, such as the Task Global Data Block,
See also:
TASK_pause (),

TASK_resume (), etc.

The first usage is in the main task (on host platforms) and in the root task (on VxWork's platforms). In both cases the user finds himself in a task/thread not created by the TASK routines, but wishes to avail himself of their functionality.

     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.

Note:
For quick and dirty applications (like test programs and shell scripting), see
See also:
TASK_cvt() and

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

int TASK_create (  TASK_tcb *  tcb,
const TASK_attr *  attributes,
TASK_entry  entry_point,
TASK_parameter  parameter
) 
 

Creates, but does not activate a task.

Parameters:
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.
Creates, but does activate a task. This allows the user to cleanly separate the definition, ie filling in the TASK_attr block, the task creation, using TASK_create(), and from the task activation.

static void task_create_hook (  WIND_TCB *  tcb  )  [static]
 

Performs additional per task creation functions.

Parameters:
tcb The VxWorks task control block
The list of per task creation functions is
  1. Add a semaphore to each newly created task

static void task_delete_hook (  WIND_TCB *  tcb  )  [static]
 

Performs per task deletion functions.

Parameters:
tcb The VxWorks tasck control block
The list of per task deletion functions are
  1. Delete the per task semaphore

int TASK_destroy (  TASK_tcb *  tcb  ) 
 

Destroys, ie deletes, a previously created task.

Parameters:
tcb The task control block of the task to destroy.
Destroys, ie deletes, previously created task. This routine will return any resources gathered by the TASK_create() utility, but will not free any user resources, such as the stack, associated with the task.

static void task_entry_safe (  int  options,
TASK_entry  usr_entry,
TASK_parameter  usr_parameter,
TASK_tcb *  tcb
)  [static]
 

Task entry point when the task is being started in a task delete safe fashion.

Parameters:
options Task startup options
usr_entry The user entry point
usr_parameter The user parameter
tcb The task's tcb
Warning:
This is an internal only routine. Documentation is provided as a possible aid in debugging.

static void task_entry_unsafe (  int  options,
TASK_entry  usr_entry,
TASK_parameter  usr_parameter,
TASK_tcb *  tcb
)  [static]
 

Task entry point when the task is being started in a task delete unsafe fashion.

Parameters:
options Task startup options
usr_entry The user entry point
usr_parameter The user parameter
tcb The task's tcb
Warning:
This is an internal only routine

void 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.

Parameters:
exit_value An arbitrary 32-bit value passed to TASK_join().
Returns:
Status, 0 = SUCCESS
Works in tandem with TASK_join to allow synchonization when a task exits. The exiting task can supply a status value, which the task calling TASK_join will receive when the task actually exits.

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.

int TASK_join (  TASK_tcb *  tcb,
void **  exit_value
) 
 

Blocks the calling task until the specified task completes.

Parameters:
tcb The task to join
exit_value Location to receive the exiting task's completion value.
Returns:
Status of the TASK_join operation.
This routine is used in conjunction with TASK_exit to provide a synchronized rundown. TASK_join() blocks the calling task until the specified task completes. If status is non-NULL it points to a location that will be filled in with the exiting task's completion value.

const char* TASK_name (  const TASK_tcb *  tcb  ) 
 

Returns a pointer to the task's name.

Parameters:
tcb The tcb of the task
Return values:
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.
Returns:
The task name, if neither of the above conditions are true.
The name of the task is maintain purely for informational and debugging reasons. The lifetime of the pointer is guaranteed only

  • On VxWorks, the lifetime of the underlying VxWorks task
  • On host platforms, the lifetime of the TASK tcb.

Explanation
On VxWorks: The name being used is the name given to the VxWorks task creation routines (taskSpawn and taskInit). The storage for this name is carved out of the first few locations of the stack associated with the task. Ergo, when the task is deleted, the name goes kaput.
On host platforms: POSIX has no facility to associate a name to a task. Therefore, the name under POSIX is a figment of TASK's imagination. The name is stored with the TASK_tcb handle. Once the handle vanishes, the name does also.

The Task Name
TASK_name always returns a non-NULL string. In most cases the string will be the name associated with the task. However, in some cases, no name can be associated with the request
  • Case 1, the tcb is specified as NULL. This means get the name of the current task. However, if the current context is the interrupt context, then there is no current task. In this case a default string of "ISR>" is returned. Since POSIX does not have an interrupt context, this string will not be returned on POSIX platforms
  • Case 2, the tcb is specified or the context is task context, but no name can be associated with the task. In this case, the string "UND>" is returned. Since, in on VxWorks platforms, all tasks are assigned a name, this string will not be returned on VxWorks platforms. On POSIX platforms, this string will be returned if the task was not created or converted by TASK.

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.

Parameters:
tcb The task control block of which task to query. If specified as NULL, the current task's priority.
Returns:
The priority level of the specified task expressed in the native tasking model's scheme.

int TASK_priority_set (  TASK_tcb *  tcb,
int  priority
) 
 

Sets priority of the specified task to the specified value.

Parameters:
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.
Returns:
Status

int TASK_resume (  TASK_tcb *  tcb  ) 
 

Resumes a previously suspended task.

Parameters:
tcb The Task Control Block of the task to resume
Returns:
Status
Warning:
This call should only be used for debugging purposes.
Note:
TASK_resumes are additive, Thus calling 5 TASK_resumes before calling any TASK_suspends means it will take 6 TASK_suspends before the task actually suspended. Because of this curious feature, calling TASK_resume with a TCB that resolves to the calling task actually makes some sense.

int TASK_revert (  TASK_tcb *  tcb  ) 
 

Strips a task/thread of its TASK functionality.

Returns:
Status
Parameters:
tcb The Task Control Block. This may be NULL, in which case the current task is reverted.
Reverts a converted task to a native task. It does this by returning the resources gathered by TASK_create(), TASK_spawn() or TASK_convert().

Although this call can be used with TASK_create() and TASK_spawn(), it is most usually called after TASK_convert().

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.

Parameters:
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.
Convenience routine to both create and activate a task.

int TASK_suspend (  TASK_tcb *  tcb  ) 
 

Suspends a task.

Parameters:
tcb The Task Control Block of the task to suspend
Returns:
Status
Warning:
This call should only be used for debugging purposes. The POSIX provides no mechanism for suspending any task but the calling task. Therefore the POSIX implementation will BUG_check if the tcb is not that of the calling task. This is not a diseaster and is in keeping with the spirit that this is a debugging routine. The warning is using this routine with a non-NULL tcb that is not the calling task's tcb is non-portable and should be avoided. The calling convention was kept to match the VxWorks convention.
Note that it is completely portable to call TASK_resume from any task. Here the reader might ask exactly the opposite question; does it make any sense to call TASK_resume with a tcb that resolves to the calling task's tcb. The answer is yes because TASK_resumes are additive, i.e. if TASK_resume is called 5 times before an TASK_suspend, it will take 6 TASK_suspends before the task actually suspends.

int TASK_sys_init (  void   ) 
 

Performs one time only initialization of the TASK facility.

Returns:
Status

int TASK_sys_shutdown (  void   ) 
 

Performs the shutdown of the TASK facility. This essentially undoes what TASK_sys_init did.

Returns:
Status

int TASK_tcb_sizeof (  void   ) 
 

Returns the size, in bytes, of a TCB to be used when creating or spawning a TASK.

Returns:
The size, in bytes, of a TCB
Use this size to allocate memory for a TASK_tcb to use when calling TASK_create() or TASK_spawn().

int TASK_wait (  const TOV  tov  ) 
 

Causes the calling task to wait (pause) until the specified timeout is reached.

Parameters:
tov The timeout value to wait until
Returns:
Status
Warning:
This call should only be used for debugging purposes. It is just a convenience routine which wrappers TASK_wait() with a timeout value calculation.

static WUT_cb_status task_wakeup (  void *  semaphore,
WUT_tmr *  tmr
)  [static]
 

Timer callback routine used in implementing TASK_wait.

Parameters:
semaphore The semaphore to give, thus unblocking the task.
tmr The WUT timer handle
Warning:
This is an internal only routine

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.

Returns:
The size, in bytes, of a TCB
Use this size to allocate memory for a TASK_tcb to use when calling TASK_convert().

Generated on Mon Nov 20 05:28:53 2006 by  doxygen 1.4.4