GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > TRC / V0-0-0

Constituent: trc     Tag: mv2304

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » SVC » source » TRC » V0-0-0 » TRC

TRC_pubdefs.h File Reference

Public definitions for the TRC trace facilities. More...

#include "PBS/FORK.h"
#include "PBS/WCT.h"

Include dependency graph for TRC_pubdefs.h:

This graph shows which files directly or indirectly include this file:


Data Structures

struct  _TRC_ForkMsg
 Structure of a fork message. More...
struct  _TRC_TraceFormat_bf
 The "index" or "table-of-contents" of a row in the trace. More...
union  _TRC_TraceFormat
 Union of the bit-field format representation and an unsigned int. More...
struct  _TRC_TraceUser
 An unstructured user contribution to a trace row. More...

Typedefs

typedef enum _TRC_LSFtype TRC_LSFtype
 Typedef for enum _TRC_LSFtype.
typedef enum _TRC_LSFversion TRC_LSFversion
 Typedef for enum _TRC_LSFversion.
typedef _TRC_ForkMsg TRC_ForkMsg
 Typedef for struct _TRC_ForkMsg.
typedef _TRC_TraceFormat_bf TRC_TraceFormat_bf
 Typedef for struct _TRC_TraceFormat_bf.
typedef _TRC_TraceFormat TRC_TraceFormat
 Typedef for struct _TRC_TraceFormat.
typedef _TRC_TraceUser TRC_TraceUser
 Typedef for struct _TRC_TraceUser.
typedef _TRC_Trace TRC_Trace
 Typedef for struct _TRC_Trace.
typedef _TRC_TraceRow TRC_TraceRow
 Typedef for struct _TRC_TraceRow.

Enumerations

enum  _TRC_LSFtype {
  TRC_LSF_DGM_TYP_STACK = 0,
  TRC_LSF_DGM_TYP_TRACE = 1
}
 Enumeration of the datagrams TRC knows how to produce. More...
enum  _TRC_LSFversion {
  TRC_LSF_DGM_VER_STACK = 0,
  TRC_LSF_DGM_VER_TRACE = 0
}
 Preallocated fork messages and their types. More...

Functions

unsigned int TRC_advertise (void)
 Use a MSG to advertise the location of the trace blob.
unsigned int TRC_copyTrace (TRC_Trace *snap, unsigned int reason)
 Workhorse to actually copy a trace snapshot.
unsigned int TRC_exceptions (unsigned int msk, unsigned int val)
 Initialize the TRC tracing facility.
unsigned int TRC_freeSnap (TRC_LSFtype type)
 Free a fork message for reuse.
unsigned int TRC_initialize (unsigned int rows)
 Initialize the TRC tracing facility.
unsigned int TRC_record (unsigned int fui, TRC_TraceUser *dat)
 Insert a record in the task trace.
unsigned int TRC_sampleTime (void)
 Place a time correlation record in the trace buffer header.
unsigned int TRC_setFork (FORK_que *fqi, FORK_cb_rtn rtn)
 Set up a destination fork queue for snapshot requests.
unsigned int TRC_setRate (unsigned int rate)
 Record the rate of forced task switches in the trace.
unsigned int TRC_shutdown (void)
 Shut down the TRC tracing facility.
unsigned int TRC_sizeofSnap (void)
 Return the buffer size needed to take a trace snapshot (bytes).
unsigned int TRC_snapStack (unsigned int dest, unsigned int reason, int tdb)
 Make a snapshot of a task's stack.
unsigned int TRC_snapTrace (unsigned int dest, unsigned int reason, unsigned int fui, TRC_TraceUser *dat)
 Make a snapshot of the current state of the trace blob.

Detailed Description

Public definitions for the TRC trace facilities. 

CVS $Id: TRC_pubdefs.h,v 1.1.1.1 2006/12/20 00:44:59 apw Exp $
Author:
A.P.Waite

Enumeration Type Documentation

enum _TRC_LSFtype
 

Enumeration of the datagrams TRC knows how to produce.

Enumerator:
TRC_LSF_DGM_TYP_STACK  Stack datagram LSF identifier
TRC_LSF_DGM_TYP_TRACE  Trace datagram LSF identifier

enum _TRC_LSFversion
 

Preallocated fork messages and their types.

Enumerator:
TRC_LSF_DGM_VER_STACK  Format of stack datagram
TRC_LSF_DGM_VER_TRACE  Format of trace datagram

Function Documentation

unsigned int TRC_copyTrace (  TRC_Trace *  snap,
unsigned int  reason
) 
 

Workhorse to actually copy a trace snapshot.

Parameters:
snap (in) Buffer into which to place the snapshot
reason (in) Reason for taking the snapshot
Return values:
TRC_NOTINIT Trace system not in state initialized
TRC_NULLPTR NULL snapshot pointer
TRC_SUCCESS Success
TRC_copyTrace() copies the current contents of the trace blob to the provided snapshot buffer.

Warning:
There is no check that the provided trace buffer blob is big enough to accomodate the trace. Use TRC_sizeofSnap() is determine how much memory to allocate.

This is a workhorse for the mLSW task. This is not the correct way to generate a trace snapshot. Use TRC_snapTrace() to do that.

unsigned int TRC_exceptions (  unsigned int  msk,
unsigned int  val
) 
 

Initialize the TRC tracing facility.

Parameters:
msk (in) Mask of exceptions to touch
val (in) Values to set masked bits to
TRC_exceptions() initiates exception tracing.

unsigned int TRC_freeSnap (  TRC_LSFtype  type  ) 
 

Free a fork message for reuse.

Parameters:
type (in) Type of fork message to free
Return values:
TRC_NOTINIT Trace system not in state initialized
TRC_SUCCESS Success

unsigned int TRC_initialize (  unsigned int  rows  ) 
 

Initialize the TRC tracing facility.

Parameters:
rows (in) Number of rows in trace buffer (default 1024)
TRC_initialize() builds up the resources to run the trace facilities.

unsigned int TRC_record (  unsigned int  fui,
TRC_TraceUser *  dat
) 
 

Insert a record in the task trace.

Parameters:
fui (in) Record format (as unsigned int)
dat (in) Record data (maximum 20 bytes)
TRC_record() records a row in the trace buffer.

A trace buffer row is data cache line aligned and one cache line long (i.e. it's 32 bytes). The first 3 longwords are owned by TRC and are used to capture a timestamp, the watchdog timeout, plus some assorted meta-information. The last 5 longwords are open to the caller of this routine. The trace will capture the 20 bytes pointed to by dat.

To distingish different record types, the user must supply a record id. While While identified as an unsigned int, it's really a short with a "facility" number encoded in the most significant byte of the short and an "instance" encoded in the least significant byte of the short. Example: when recording entrancies and exits of exception handlers, the "facility" is (a small integer representing) "exception" and the instances are (small integers representing) "entrance" and "exit".

unsigned int TRC_sampleTime (  void   ) 
 

Place a time correlation record in the trace buffer header.

Return values:
TRC_NOTINIT Trace system not in state initialized
TRC_SUCCESS Success
TRC_sampleTime() samples wall clock time and CPU timebase register time (as quickly as it can manage), and stores the results in the trace buffer. The intent is that the timebase register times captured by the trace can be converted later to wall clock time.

unsigned int TRC_setFork (  FORK_que *  fqi,
FORK_cb_rtn  rtn
) 
 

Set up a destination fork queue for snapshot requests.

Parameters:
fqi (in) Fork queue handle
rtn (in) Fork queue routine
Return values:
TRC_NOTINIT Trace system not in state initialized
TRC_SUCCESS Success

unsigned int TRC_setRate (  unsigned int  rate  ) 
 

Record the rate of forced task switches in the trace.

Parameters:
rate (in) Rate of forced task switches (millseconds)
Return values:
TRC_NOTINIT Trace system not in state initialized
TRC_SUCCESS Success

unsigned int TRC_shutdown (  void   ) 
 

Shut down the TRC tracing facility.

TRC_shutdown() shuts down the trace facilities.

unsigned int TRC_sizeofSnap (  void   ) 
 

Return the buffer size needed to take a trace snapshot (bytes).

Return values:
0 Trace system not initialized
x Size needed to accomodate a trace (bytes)

unsigned int TRC_snapStack (  unsigned int  dest,
unsigned int  reason,
int  tdb
) 
 

Make a snapshot of a task's stack.

Parameters:
dest (in) Destination (0 => 1553, 1 => SDI)
reason (in) User statement about the reason for the dump
tdb (in) Task ID to dump (-1 => "self") (CPU_DB/ITC definition)
Return values:
TRC_CPUTSKID Unrecognized (CPU_DB) task ID
TRC_FORKBAD Cannot queue to destination fork
TRC_FORKDST Destination fork queue not initialized
TRC_NOTINIT Trace system not in state initialized
TRC_NOSTACK Cannot snapshot task stacks on host machines
TRC_STKSNPAC Task stack snapshot already active
TRC_SUCCESS Success
TRC_VXWTSKID Unrecognized (VxWorks) task ID
TRC_snapStack() tells TRC to task a stack snapshot.

unsigned int TRC_snapTrace (  unsigned int  dest,
unsigned int  reason,
unsigned int  fui,
TRC_TraceUser *  dat
) 
 

Make a snapshot of the current state of the trace blob.

Parameters:
dest (in) Destination (0 => 1553, 1 => SDI)
reason (in) User statement about the reason for the dump
fui (in) Record format (as unsigned int)
dat (in) User block of information
Return values:
TRC_FORKBAD Cannot queue to destination fork
TRC_FORKDST Destination fork queue not initialized
TRC_NOTINIT Trace system not in state initialized
TRC_SUCCESS Success
TRC_TRCSNPAC Trace snapshot already active
TRC_snapStack() tells TRC to task a trace snapshot.

When taking a snapshot of the trace buffer, this routine will insert a record to indicate the time at which the snapshot was taken. This amounts to making a call to TRC_record() and the fmt and dat parameters to this routine are simply passed through to the TRC_record() call, to allow the caller of this routine do "individualize" the inserted trace record.

Generated on Wed Dec 20 09:24:33 2006 by  doxygen 1.4.4