---

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

Constituent: trc     Tag: rad750

---

         

---

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"

Include dependency graph for TRC_snap.c:

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 (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, 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.2 2007/03/22 01:47:40 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.

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.

static unsigned char * formatHeader (  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.

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

static void snapInitialize (  unsigned int  len, 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.

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

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.

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

void TRC_freeSnap (  TRC_SnapTrace *  snp  )

Free a trace snapshot buffer. Parameters: snp  (in) Snapshot buffer handle TRC_freeSnap() frees a 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. 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).

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.

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.

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.

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.

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.

---