GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> TRC / V1-0-8 > trc / rhel5-32

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

TRC_snap.c File Reference

Facilities to snapshot a task trace blob. More...

#include <string.h>
#include <CCSDS/CCSDS_pkt.h>
#include <LSF/LSF.h>
#include <LSF/LSF_ids.h>
#include <MDB/MDB_pubdefs.h>
#include <PBS/FORK.h>
#include <PBS/MBA.h>
#include <PBS/RW.ih>
#include <TRC/TRC_msgs.h>
#include <TRC_prvdefs.h>

Functions

static TRC_SnapTrace * allocSnap (TRC_Buffer *trc)
 Allocate a snapshot buffer.
static FORK_cb_status forkSnapTrace (FORK_cb_prm *prm, FORK_msg_hdr *hdr)
 Service a request to take a trace buffer snapshot.
static unsigned char * formatHeader (unsigned char *qipay, unsigned int size, WCT_time when, unsigned int apid)
 Format the header of a telemetry block.
static void sendSDI_cb (ITC_QueueItem *qitem, unsigned int status, void *prm0, void *prm1, void *prm2, unsigned int tx)
 Clean up after sending a trace snapshot to the SDI.
static void snapInitialize (unsigned int len, unsigned char *mem, unsigned int pkt, unsigned int off)
 Initialize a snapshot buffer.
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_detachSnap (TRC_Buffer *trc)
 Detach snapshot buffers to a trace.
void TRC_freeSnap (TRC_SnapTrace *snp)
 Free a trace snapshot buffer.
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.
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.

Detailed Description

Facilities to snapshot a task trace blob. 

CVS $Id: TRC_snap.c,v 1.4 2011/03/29 00:59:53 apw Exp $
Author:
A.P.Waite
TRC_snap.c provides facilities to snapshot an active task switch trace buffer.

Warning:
Suitable task tracing facilities are not available on host systems, so while this facility can be compiled and linked on host systems, it cannot perform a run time trace of task switches. It can still, however, record events generated by TRC_insert() calls.

Function Documentation

static TRC_SnapTrace * allocSnap ( TRC_Buffer *  trc  )  [inline, static]

Allocate a snapshot buffer.

Parameters:
trc (in) Trace buffer handle
allocSnap() allocates a snapshot buffer to capture a trace snapshot. This will only succeed is snapshot buffers have been attached to the trace (see TRC_attachSnap()), and a snapshot buffer is free.

References _TRC_Buffer::fcb, and _TRC_Buffer::nam.

Referenced by TRC_snapTrace().

static FORK_cb_status forkSnapTrace ( FORK_cb_prm *  prm,
FORK_msg_hdr *  hdr 
) [static]

Service a request to take a trace buffer snapshot.

forkSnapTrace() services a request to take a trace buffer snapshot.

References _TRC_Control::com, _TRC_SnapTrace::copy, formatHeader(), _TRC_SnapTrace::len, LSW_APID_SDI_BASE, _TRC_SnapTrace::prm, _TRC_SnapTrace::qipay, _TRC_SnapTrace::reason, _TRC_SnapTrace::rtn, _TRC_Common::size, _TRC_Buffer::size, _TRC_SnapTrace::trc, TRC_copy(), TRC_freeSnap(), TRC_tcb, and _TRC_SnapTrace::when.

Referenced by TRC_snapTrace().

static unsigned char * formatHeader ( unsigned char *  qipay,
unsigned int  size,
WCT_time  when,
unsigned int  apid 
) [inline, static]

Format the header of a telemetry block.

Parameters:
qipay (in) Start of CCSDS header
size (in) Size of snapshot (just the data portion, in bytes)
when (in) Timestamp to place in CCSDS header
apid (in) APID to place in CCSDS header
Return values:
NULL Format failed
x Pointer to the snapshot contributor buffer
formatHeader() formats the header portions of a telemetry block. It assumes an SDI target, so the routine that sends the telemetry to the CTDB will have to do a little extra work on the CCSDS portion of the header.

References LSW_LSF_DGM_TYP_TRACE, and LSW_LSF_DGM_VER_TRACE.

Referenced by forkSnapTrace().

static void sendSDI_cb ( ITC_QueueItem *  qitem,
unsigned int  status,
void *  prm0,
void *  prm1,
void *  prm2,
unsigned int  tx 
) [static]

Clean up after sending a trace snapshot to the SDI.

Parameters:
qitem (in) Queue item
status (in) Status from ITC_send()
prm0 (in) User param 0 (Snapshot buffer)
prm1 (in) User param 1 (unused)
prm2 (in) User param 2 (unused)
tx (in) Failure during send phase of ITC_send() (unused)
sendSDI_cb() is a standard ITC completion routine. It simply frees the the snapshot back into its FPA pool (unless it's the start line trace ... it never frees the start line trace).

References _TRC_Buffer::fcb, _TRC_SnapTrace::reason, and _TRC_SnapTrace::trc.

Referenced by TRC_sendSDI().

static void snapInitialize ( unsigned int  len,
unsigned char *  mem,
unsigned int  pkt,
unsigned int  off 
) [static]

Initialize a snapshot buffer.

Parameters:
len (in) User parameter used to send queue item length
mem (in) Pointer to start of packet
pkt (in) Size of packet (unused)
off (in) Offset of packet control block (unused)
snapInitialize() is an FPA initialization routine used to set up the constant parts of the snapshot buffers.

References _TRC_SnapTrace::qilen, _TRC_SnapTrace::qipay, and _TRC_SnapTrace::qitem.

Referenced by TRC_attachSnap().

unsigned int TRC_attachSnap ( TRC_Buffer *  trc,
unsigned int  cnt 
)

Attach snapshot buffers to a trace.

Parameters:
trc (in) Trace buffer handle
cnt (in) Number of buffers (usually one)
TRC_attachSnap() creates a snapshot buffer(s) and attaches it to an existing trace buffer. The most common case is to attach a single snapshot buffer (it doesn't often make sense to overlap two snapshots). The case of the "system" trace is anomalous and uses two snapshot buffers (one to capture and hold the start line trace).

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

Parameters:
dtrc (in) Destination buffer
strc (in) Source trace buffer (NULL => system trace)
reason (in) Reason for taking the snapshot
Return values:
TRC_NOTINIT Trace system not in state initialized
TRC_NOTTRACE Not a trace buffer
TRC_SUCCESS Success
TRC_copy() copies the current contents of a indicated trace buffer, followed by the current contents of the trace common area, to the the buffer indicated by dtrc.

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_detachSnap ( TRC_Buffer *  trc  ) 

Detach snapshot buffers to a trace.

Parameters:
trc (in) Trace buffer handle
TRC_detachSnap() detaches a trace's snapshot buffer(s) (if present).

References _TRC_Buffer::fcb, _TRC_Control::rwi, TRC_tcb, and TRC_validTrace().

void TRC_freeSnap ( TRC_SnapTrace *  snp  ) 

Free a trace snapshot buffer.

Parameters:
snp (in) Snapshot buffer handle
TRC_freeSnap() frees a snapshot buffer.

References _TRC_Buffer::fcb, _TRC_SnapTrace::reason, and _TRC_SnapTrace::trc.

Referenced by forkSnapTrace(), TRC_sendCTDB(), TRC_sendFile(), TRC_sendSDI(), and TRC_snapTrace().

unsigned int TRC_saveStart ( void *  prm,
unsigned int  len,
TRC_SnapTrace *  snp,
TRC_Buffer *  trc 
)

Save the start line trace in a safe place.

Parameters:
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)
Return values:
TRC_STARTDUN Start line trace already captured
TRC_SUCCESS Success
TRC_saveStart() is an instance of a "trace disposition" callback routine. This instance is highly specialized and is used once only at the end of the start line to save the start line trace in a safe place (for later retrieval by TRC_sendStart() if that is commanded).

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.

Parameters:
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)
Return values:
TRC_GENERROR Always (not implemented)
Warning:
This function not yet implemented.
TRC_sendCTDB() is an instance of a "trace disposition" callback routine. This instance simply parcels up and sends a snapshot to the 1553.

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.

Parameters:
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)
Return values:
x Return code from TRC_write()
TRC_sendFile() is an instance of a "trace disposition" callback routine. This instance writes the trace section only of a snapshot to a file.

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.

Parameters:
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)
Return values:
TRC_SUCCESS Success
x Failure code from ITC_bind() or ITC_send()
TRC_sendSDI() is an instance of a "trace disposition" callback routine. This instance simply parcels up and sends a snapshot to the science data interface.

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.

Parameters:
dest (in) Destination for snapshot
TRC_sendStart() sends the start line trace to the indicated destination.

References _TRC_Control::start, _TRC_Control::state, TRC_CTL_INITIALIZED, TRC_sendCTDB(), TRC_sendSDI(), TRC_SNAP_DEST_CTDB, and TRC_tcb.

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.

Parameters:
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
TRC_snapTrace() initiates the process of taking a trace buffer snapshot. The snapshot does not occur inline with this call because this call may be made from a low priority task, which has no chance of performing a coherent hot snapshot (especially if the target of the snapshot is the system trace). Instead, this routine composes a snapshot request which it sends to a high priority task (usually "mLSW").

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.

Generated on Tue Nov 29 20:28:00 2011 by  doxygen 1.5.8