GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> TRC / V1-0-8 > trc / rhel6-32
#include <PBS/FORK.h>
#include <TEX/TEX_pubdefs.h>
Defines | |
#define | TRC_M_BUFFER (0x54524301) |
Framing word at start of a trace buffer ("TRC" || 1). | |
#define | TRC_M_COMMON (0x54434d01) |
Framing word at start of the trace common area ("TCM" || 1). | |
#define | TRC_L_TRACENAME (16) |
Longest trace name (including terminator). | |
#define | LSW_APID_SDI_BASE (0x3e3) |
Base of APID range for dumping LSW datagrams to the SDI. | |
#define | LSW_LSF_DGM_TYP_TRACE (0) |
Framing word at start of a trace buffer ("TRC" || 1). | |
#define | LSW_LSF_DGM_VER_TRACE (0) |
Framing word at start of the trace common area ("TCM" || 1). | |
Typedefs | |
typedef enum _TRC_SnapDest | TRC_SnapDest |
Typedef for enum _TRC_SnapDest. | |
typedef struct _TRC_Buffer | TRC_Buffer |
Typedef for struct _TRC_Buffer. | |
typedef struct _TRC_Monitor | TRC_Monitor |
Typedef for struct _TRC_Monitor. | |
typedef struct _TRC_SnapTrace | TRC_SnapTrace |
Typedef for struct _TRC_SnapTrace. | |
typedef struct _TRC_Top | TRC_Top |
Typedef for struct _TRC_Top. | |
typedef unsigned int | TRC_cb_Dispose (void *prm, unsigned int len, TRC_SnapTrace *snp, TRC_Buffer *trc) |
Disposition routine for a trace snapshot. | |
Enumerations | |
enum | _TRC_SnapDest { TRC_SNAP_DEST_CTDB = 0, TRC_SNAP_DEST_SDI = 1 } |
Possible telemetry destinations for a trace snapshot. More... | |
Functions | |
unsigned int | TRC_advertise (TRC_Buffer *trc) |
Use a MSG to advertise the location of the system trace blob. | |
unsigned int | TRC_attachSnap (TRC_Buffer *trc, unsigned int cnt) |
Attach snapshot buffers to a trace. | |
unsigned int | TRC_copy (TRC_Buffer *dtrc, TRC_Buffer *strc, unsigned int reason) |
Make a coherent copy of a trace buffer (if possible). | |
unsigned int | TRC_correlateTime (TRC_Buffer *trc) |
Place a time correlation record in a trace buffer header. | |
unsigned int | TRC_create (TRC_Buffer **trc, unsigned int rows, unsigned int id, const char *nam) |
Create a user trace buffer (no snaphost or telemetry capability). | |
unsigned int | TRC_delete (TRC_Buffer *trc) |
Create a user trace buffer. | |
unsigned int | TRC_detachSnap (TRC_Buffer *trc) |
Detach snapshot buffers to a trace. | |
unsigned int | TRC_differMonitor (TRC_Monitor *old, TRC_Monitor *new, TRC_Top *top) |
Take the difference between monitor snapshots. | |
void | TRC_freeSnap (TRC_SnapTrace *snp) |
Free a trace snapshot buffer. | |
WCT_time_sat | TRC_getTopTime (TRC_Top *top) |
Get the timestamp from a differential monitor record. | |
unsigned int | TRC_ID2Trace (unsigned int id, TRC_Buffer **trc) |
Convert a trace identity to a trace buffer handle. | |
unsigned int | TRC_initialize (unsigned int rows, unsigned int enable) |
Initialize the tracing facility. | |
unsigned int | TRC_name2Trace (const char *nam, TRC_Buffer **trc) |
Convert a trace identity to a trace buffer handle. | |
unsigned long long | TRC_record (TRC_Buffer *trc, unsigned int fui, unsigned int *dat) |
Insert a record into a trace. | |
unsigned int | TRC_saveStart (void *prm, unsigned int len, TRC_SnapTrace *snp, TRC_Buffer *trc) |
Save the start line trace in a safe place. | |
unsigned int | TRC_sendCTDB (void *prm, unsigned int len, TRC_SnapTrace *snp, TRC_Buffer *trc) |
Send a snapshot to the science data interface. | |
unsigned int | TRC_sendFile (void *prm, unsigned int len, TRC_SnapTrace *snp, TRC_Buffer *trc) |
Send the trace from a snapshot to a file. | |
unsigned int | TRC_sendSDI (void *prm, unsigned int len, TRC_SnapTrace *snp, TRC_Buffer *trc) |
Send a snapshot to the science data interface. | |
unsigned int | TRC_sendStart (TRC_SnapDest dest) |
Send the start line trace to the indicated destination. | |
FORK_que * | TRC_setFork (FORK_que *fqi) |
Convert a trace name to a trace buffer pointer. | |
unsigned int | TRC_sizeofMonitor (void) |
The size of a buffer to accomodate a task monitor snapshot. | |
unsigned int | TRC_sizeofTop (void) |
The size of a buffer to accomodate a task monitor snapshot. | |
unsigned int | TRC_sizeofTrace (TRC_Buffer *trc) |
Return the size of a complete compound trace (buffer plus common). | |
unsigned int | TRC_snapMonitor (TRC_Monitor *mon) |
Snapshot the task monitor structure. | |
unsigned int | TRC_snapTrace (TRC_Buffer *trc, unsigned int reason, TRC_cb_Dispose *rtn, void *prm, unsigned int len) |
Snapshot a trace and send the output to a (telemetry) destination. | |
int | TRC_tdb2tid (int tdb) |
Translate a task ID (CPU_DB/ITC style) to a VxWorks task ID. | |
unsigned int | TRC_write (TRC_Buffer *trc, const char *fil) |
Write a (compound) trace snapshot to a file. |
CVS $Id: TRC_pubdefs.h,v 1.4 2011/03/29 00:59:53 apw Exp $
enum _TRC_SnapDest |
unsigned int TRC_advertise | ( | TRC_Buffer * | trc | ) |
Use a MSG to advertise the location of the system trace blob.
TRC_NOTINIT | System trace not in state initialized | |
TRC_SUCCESS | Success |
References _TRC_Control::com, _TRC_Buffer::id, _TRC_Buffer::nam, _TRC_Control::nxt, _TRC_Common::size, _TRC_Buffer::size, TRC_tcb, and TRC_validTrace().
unsigned int TRC_attachSnap | ( | TRC_Buffer * | trc, | |
unsigned int | cnt | |||
) |
Attach snapshot buffers to a trace.
trc | (in) Trace buffer handle | |
cnt | (in) Number of buffers (usually one) |
References _TRC_Control::com, _TRC_Buffer::fcb, _TRC_Buffer::nam, _TRC_Control::rwi, _TRC_Common::size, _TRC_Buffer::size, snapInitialize(), TRC_tcb, and TRC_validTrace().
Referenced by TRC_initialize().
unsigned int TRC_copy | ( | TRC_Buffer * | dtrc, | |
TRC_Buffer * | strc, | |||
unsigned int | reason | |||
) |
Make a coherent copy of a trace buffer (if possible).
dtrc | (in) Destination buffer | |
strc | (in) Source trace buffer (NULL => system trace) | |
reason | (in) Reason for taking the snapshot |
TRC_NOTINIT | Trace system not in state initialized | |
TRC_NOTTRACE | Not a trace buffer | |
TRC_SUCCESS | Success |
References _TRC_Buffer::chk, _TRC_Common::chk, _TRC_Buffer::com, _TRC_Buffer::count, _TRC_Buffer::last, _TRC_Buffer::max, _TRC_Buffer::min, _TRC_Task2Name::nam, _TRC_Buffer::reason, _TRC_Buffer::row, _TRC_Buffer::rows, _TRC_Control::rwi, _TRC_Buffer::size, _TRC_Common::strbas, _TRC_Common::strmax, _TRC_Common::t2nbas, _TRC_Top::tim, TRC_tcb, TRC_TSK_OTHER, TRC_validTrace(), and _TRC_Buffer::under.
Referenced by forkSnapTrace().
unsigned int TRC_correlateTime | ( | TRC_Buffer * | trc | ) |
Place a time correlation record in a trace buffer header.
TRC_NOTINIT | System trace not in state initialized | |
TRC_NOTTRACE | Invalid trace pointer | |
TRC_SUCCESS | Success |
References _TRC_Buffer::itic, _TRC_Buffer::itim, _TRC_Control::rwi, TRC_tcb, and TRC_validTrace().
unsigned int TRC_create | ( | TRC_Buffer ** | trc, | |
unsigned int | rows, | |||
unsigned int | id, | |||
const char * | nam | |||
) |
Create a user trace buffer (no snaphost or telemetry capability).
trc | (out) Trace buffer handle | |
rows | (in) Number of rows in trace buffer (default 1024) | |
id | (in) Trace identity (user defined, a number 1-255) | |
nam | (in) Trace name (user defined, 15 characters max) |
TRC_ALLOCMEM | Cannot allocate memory | |
TRC_PARMNULL | NULL parameter detected | |
TRC_NOTINIT | System trace not in state initialized | |
TRC_SUCCESS | Success |
References _TRC_Buffer::chk, _TRC_Control::com, _TRC_Buffer::com, _TRC_Buffer::frame, _TRC_Buffer::id, _TRC_Buffer::max, _TRC_Buffer::min, _TRC_Buffer::nam, _TRC_Buffer::nxt, _TRC_Control::nxt, _TRC_Buffer::row, _TRC_Buffer::rows, _TRC_Control::rwi, _TRC_Buffer::size, _TRC_Control::state, TRC_CACHE_LINE_PAD, TRC_CTL_INITIALIZED, TRC_L_ROWS_MAX, TRC_L_ROWS_MIN, TRC_M_BUFFER, TRC_tcb, and validName().
unsigned int TRC_delete | ( | TRC_Buffer * | trc | ) |
Create a user trace buffer.
trc | (in) Trace buffer handle |
TRC_NOSYSDEL | Cannot delete the system trace | |
TRC_NOTTRACE | Not a vlid trace pointer | |
TRC_SUCCESS | Success |
References _TRC_Buffer::fcb, _TRC_Buffer::nxt, _TRC_Control::nxt, _TRC_Control::rwi, TRC_tcb, and TRC_validTrace().
unsigned int TRC_detachSnap | ( | TRC_Buffer * | trc | ) |
Detach snapshot buffers to a trace.
trc | (in) Trace buffer handle |
References _TRC_Buffer::fcb, _TRC_Control::rwi, TRC_tcb, and TRC_validTrace().
unsigned int TRC_differMonitor | ( | TRC_Monitor * | old, | |
TRC_Monitor * | new, | |||
TRC_Top * | top | |||
) |
Take the difference between monitor snapshots.
old | (in) Record at start of sampling period | |
new | (in) Record at end of sampling period | |
top | (out) Differential monitor record |
TRC_MONMATCH | Monitor record serial numbers do not match | |
TRC_NOCALC | Time mis-ordered (or zero), cannot calculate | |
TRC_NOOLDMON | Older monitor buffer not valid for differencing | |
TRC_NOTMON | Invalid monitor record | |
TRC_PARMNULL | NULL parameter detected | |
TRC_SUCCESS | Success |
References _TRC_Monitor::cnt, _TRC_TaskCount::dtics, _TRC_Top::dtim, _TRC_TaskCount::enter, _TRC_Top::ex5, _TRC_Top::ex9, _TRC_Top::freq, _TRC_Monitor::itic, _TRC_Monitor::itim, _TRC_Top::serial, _TRC_Monitor::serial, _TRC_Top::tim, _TRC_Top::top, TRC_L_TASKLIST, TRC_TSK_OTHER, and _TRC_Monitor::when.
void TRC_freeSnap | ( | TRC_SnapTrace * | snp | ) |
Free a trace snapshot buffer.
snp | (in) Snapshot buffer handle |
References _TRC_Buffer::fcb, _TRC_SnapTrace::reason, and _TRC_SnapTrace::trc.
Referenced by forkSnapTrace(), TRC_sendCTDB(), TRC_sendFile(), TRC_sendSDI(), and TRC_snapTrace().
WCT_time_sat TRC_getTopTime | ( | TRC_Top * | top | ) |
Get the timestamp from a differential monitor record.
top | (in) Differential monitor record |
0 | Invalid structure pointer | |
x | Timestamp in WCT_sat_time format |
References _TRC_Top::tim.
unsigned int TRC_ID2Trace | ( | unsigned int | id, | |
TRC_Buffer ** | trc | |||
) |
Convert a trace identity to a trace buffer handle.
id | (in) Trace identification number (user defined) | |
trc | (out) Trace buffer handle |
TRC_NOSCHID | No trace with this identifier | |
TRC_NOTINIT | Trace system not in state initialized | |
TRC_SUCCESS | Success |
References _TRC_Buffer::nxt, _TRC_Control::nxt, _TRC_Control::state, and TRC_CTL_INITIALIZED.
unsigned int TRC_initialize | ( | unsigned int | rows, | |
unsigned int | enable | |||
) |
Initialize the tracing facility.
rows | (in) Number of rows in system trace buffer (default 1024) | |
enable | (in) System trace elements to enable |
TRC_ADDHOOK | Cannot add task switch hook routine | |
TRC_ALLOCMEM | Cannot allocate memory | |
TRC_ALLOCMTX | Cannot allocate mutex | |
TRC_BADSTATE | Invalid state for operation | |
TRC_SUCCESS | Success |
References _TRC_Control::chk, _TRC_Common::chk, _TRC_Buffer::chk, _TRC_Control::com, _TRC_Buffer::com, _TRC_Control::exc, _TRC_Common::frame, _TRC_Buffer::frame, _TRC_Common::freq, _TRC_Buffer::max, _TRC_Buffer::min, _TRC_Control::mtx, _TRC_Task2Name::nam, _TRC_Buffer::nam, _TRC_Control::nxt, _TRC_Buffer::row, _TRC_Buffer::rows, _TRC_Control::rwi, _TRC_Common::serial, _TRC_Common::size, _TRC_Buffer::size, _TRC_Control::state, _TRC_Common::strbas, _TRC_Common::strmax, _TRC_Common::t2nbas, _TRC_Common::t2ncnt, TRC_attachSnap(), TRC_CACHE_LINE_PAD, TRC_CTL_BROKEN, TRC_CTL_INITIALIZED, TRC_CTL_UNINITIALIZED, TRC_L_ROWS_DEFAULT, TRC_L_ROWS_MAX, TRC_L_SEED, TRC_L_TASKLIST, TRC_L_TASKNAME, TRC_M_BUFFER, TRC_M_COMMON, and TRC_TSK_OTHER.
unsigned int TRC_name2Trace | ( | const char * | nam, | |
TRC_Buffer ** | trc | |||
) |
Convert a trace identity to a trace buffer handle.
nam | (in) Trace name (user defined) | |
trc | (out) Trace buffer handle |
TRC_NOSCHNAM | No trace with this name | |
TRC_NOTINIT | Trace system not in state initialized | |
TRC_SUCCESS | Success |
References _TRC_Buffer::nxt, _TRC_Control::nxt, _TRC_Control::state, and TRC_CTL_INITIALIZED.
unsigned long long TRC_record | ( | TRC_Buffer * | trc, | |
unsigned int | fui, | |||
unsigned int * | dat | |||
) |
Insert a record into a trace.
trc | (in) Trace buffer to use (NULL => "system" trace buffer) | |
fui | (in) Record format | |
dat | (in) Record data (always 6 longwords = 24 bytes) |
x | The timestamp captured from the CPU time-base register |
A trace buffer row is data cache line aligned and one cache line long (i.e. it's 32 bytes). The contents of the first eight bytes are defined by TRC. The first four bytes capture the low half of of the CPU's time base register, the next two bytes capture the information that allows the trace dump routine to figure out how to format the dump. The third byte records the task ID of the task in scope during which the call to TRC_record(). The last byte is reserved.
The caller's responsibility is to put formatting information into the upper two bytes of fui, and fill in 24 bytes of user data into dat.
References _TRC_Control::chk, _TRC_Buffer::frame, _TRC_Buffer::max, _TRC_Buffer::min, _TRC_Control::nxt, record(), recover(), _TRC_Buffer::row, _TRC_Buffer::rows, _TRC_Control::rwi, TRC_M_BUFFER, and TRC_tcb.
unsigned int TRC_saveStart | ( | void * | prm, | |
unsigned int | len, | |||
TRC_SnapTrace * | snp, | |||
TRC_Buffer * | trc | |||
) |
Save the start line trace in a safe place.
prm | (in) User parameter block | |
len | (in) User parameter block length | |
snp | (in) The snapshot buffer handle | |
trc | (in) The trace buffer handle (the copy in the snapshot) |
TRC_STARTDUN | Start line trace already captured | |
TRC_SUCCESS | Success |
References _TRC_SnapTrace::reason, _TRC_Control::start, and TRC_tcb.
unsigned int TRC_sendCTDB | ( | void * | prm, | |
unsigned int | len, | |||
TRC_SnapTrace * | snp, | |||
TRC_Buffer * | trc | |||
) |
Send a snapshot to the science data interface.
prm | (in) User parameter block | |
len | (in) User parameter block length | |
snp | (in) The snapshot buffer handle | |
trc | (in) The trace buffer handle (the copy in the snapshot) |
TRC_GENERROR | Always (not implemented) |
References TRC_freeSnap().
Referenced by TRC_sendStart().
unsigned int TRC_sendFile | ( | void * | prm, | |
unsigned int | len, | |||
TRC_SnapTrace * | snp, | |||
TRC_Buffer * | trc | |||
) |
Send the trace from a snapshot to a file.
prm | (in) User parameter block | |
len | (in) User parameter block length | |
snp | (in) The snapshot buffer handle | |
trc | (in) The trace buffer handle (the copy in the snapshot) |
x | Return code from TRC_write() |
References TRC_freeSnap(), and TRC_write().
unsigned int TRC_sendSDI | ( | void * | prm, | |
unsigned int | len, | |||
TRC_SnapTrace * | snp, | |||
TRC_Buffer * | trc | |||
) |
Send a snapshot to the science data interface.
prm | (in) User parameter block | |
len | (in) User parameter block length | |
snp | (in) The snapshot buffer handle | |
trc | (in) The trace buffer handle (the copy in the snapshot) |
TRC_SUCCESS | Success | |
x | Failure code from ITC_bind() or ITC_send() |
References _TRC_SnapTrace::qilen, _TRC_SnapTrace::qipay, _TRC_SnapTrace::qitem, sendSDI_cb(), and TRC_freeSnap().
Referenced by TRC_sendStart().
unsigned int TRC_sendStart | ( | TRC_SnapDest | dest | ) |
Send the start line trace to the indicated destination.
dest | (in) Destination for snapshot |
References _TRC_Control::start, _TRC_Control::state, TRC_CTL_INITIALIZED, TRC_sendCTDB(), TRC_sendSDI(), TRC_SNAP_DEST_CTDB, and TRC_tcb.
FORK_que * TRC_setFork | ( | FORK_que * | fqi | ) |
Convert a trace name to a trace buffer pointer.
fqi | (in) Set the fork queue trace should use for snapshots |
References _TRC_Control::fqi, _TRC_Control::rwi, _TRC_Control::state, and TRC_CTL_INITIALIZED.
unsigned int TRC_sizeofMonitor | ( | void | ) |
The size of a buffer to accomodate a task monitor snapshot.
x | Size of a buffer to hold a task monitor snapshot |
unsigned int TRC_sizeofTop | ( | void | ) |
The size of a buffer to accomodate a task monitor snapshot.
x | Size of a buffer to hold a task monitor snapshot |
unsigned int TRC_sizeofTrace | ( | TRC_Buffer * | trc | ) |
Return the size of a complete compound trace (buffer plus common).
trc | (in) Trace buffer (NULL => system trace) |
0 | Cannot locate trace buffer | |
x | Size of a complete trace buffer |
In normal operation, there can be one or more TRC_Buffer structures, but only one TRC_Common area. The "system trace" has the privilege of having the TRC_Common located area contiguously behind the TRC_Buffer area.
TRC_sizeTrace() can therefore be used two ways. When called with a NULL pointer, it returns the size of the extant system trace (system trace buffer plus common area). When called with a pointer to a user trace buffer, it returns the size of a buffer necessary to accomodate the common area and the user's trace buffer back-to-back (with all necessary padding). The latter can be useful for user manipulation of trace buffers via facilities like TRC_copy().
References _TRC_Control::com, _TRC_Common::size, _TRC_Buffer::size, TRC_tcb, and TRC_validTrace().
unsigned int TRC_snapMonitor | ( | TRC_Monitor * | mon | ) |
Snapshot the task monitor structure.
mon | (out) Where to put the results |
TRC_PARMNULL | NULL parameter detected | |
TRC_NOTINIT | Trace system not in state initialized | |
TRC_SUCCESS | Success |
References _TRC_Task2Name::cnt, _TRC_Monitor::cnt, _TRC_Control::com, _TRC_TaskCount::dtics, _TRC_TaskCount::enter, _TRC_Common::freq, _TRC_Monitor::freq, _TRC_Buffer::itic, _TRC_Monitor::itic, _TRC_Buffer::itim, _TRC_Monitor::itim, _TRC_Buffer::last, _TRC_Control::nxt, _TRC_Common::serial, _TRC_Monitor::serial, _TRC_Control::state, _TRC_Common::t2nbas, TRC_CTL_INITIALIZED, TRC_L_TASKLIST, TRC_tcb, and _TRC_Monitor::when.
unsigned int TRC_snapTrace | ( | TRC_Buffer * | trc, | |
unsigned int | reason, | |||
TRC_cb_Dispose * | rtn, | |||
void * | prm, | |||
unsigned int | len | |||
) |
Snapshot a trace and send the output to a (telemetry) destination.
trc | (in) Trace buffer handle | |
reason | (in) Reason the snapshot is beaing made | |
rtn | (in) Disposition callback routine | |
prm | (in) User parameter block | |
len | (in) Length of user parameter block |
The parameters rtn, prm, and len are user defined and specify a "disposition" for the snapshot once the high priority task has captured it. The definition of rtn follows the normal conventions for a callback routine (in this case, is must follow the prototype TRC_cb_Dispose). prm and len are slightly less conventional. It's difficult to predict what a user disposition might look like, and how much user data is needed to parameterize it, so the solution adopted here is to reserve a fairly large "user parameter block" in the snapshot request (TRC_L_USERPARM bytes long) then simply copy through anything the user wants to put in there. The poster child for a callback that needs a fairly big user parameter block would be a routine that writes the captured snapshot out to a file, but needs to know the name of the file to open. That could be accomplished with an indirect pointer of course, but then caller needs to arrange for the memory to persist until the file writing is complete and then arrange for that memory's disposal. All in all, it's easier if the caller can just store the file name along with the request and have done.
References allocSnap(), forkSnapTrace(), _TRC_Control::fqi, _TRC_SnapTrace::prm, _TRC_SnapTrace::reason, _TRC_SnapTrace::rtn, _TRC_SnapTrace::trc, TRC_freeSnap(), TRC_L_USERPARM, TRC_tcb, TRC_validTrace(), and _TRC_SnapTrace::when.
int TRC_tdb2tid | ( | int | tdb | ) |
Translate a task ID (CPU_DB/ITC style) to a VxWorks task ID.
tdb | (in) Task ID (CPU_DB/ITC definition) (0 => "self") |
0 | No translation available | |
x | VxWorks task ID |
References _TRC_Control::chk, _TRC_Control::com, _TRC_Common::t2nbas, _TRC_Task2Name::tid, TRC_L_TASKLIST, and TRC_tcb.
unsigned int TRC_write | ( | TRC_Buffer * | trc, | |
const char * | fil | |||
) |
Write a (compound) trace snapshot to a file.
trc | (in) The buffer handle | |
fil | (in) File name |
References _TRC_Buffer::frame, _TRC_Common::size, _TRC_Buffer::size, and TRC_M_BUFFER.
Referenced by TRC_sendFile().