TRC_pubdefs.h File Reference

Public definitions for the TRC facilities. More...

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

---

Detailed Description

Public definitions for the TRC facilities.

CVS $Id: TRC_pubdefs.h,v 1.4 2011/03/29 00:59:53 apw Exp $

Author:

A.P.Waite

---

Enumeration Type Documentation

enum _TRC_SnapDest

Possible telemetry destinations for a trace snapshot.

Enumerator:

TRC_SNAP_DEST_CTDB	Send to CTDB (not implemented)
TRC_SNAP_DEST_SDI	Send to SDI

---

Function Documentation

unsigned int TRC_advertise

(

TRC_Buffer *

trc

)

Use a MSG to advertise the location of the system trace blob.

Return values:

	TRC_NOTINIT	System trace not in state initialized
	TRC_SUCCESS	Success

TRC_advertise() issues an informational message stating where the system trace buffer is located in memory.

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.

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_correlateTime

(

TRC_Buffer *

trc

)

Place a time correlation record in a trace buffer header.

Return values:

	TRC_NOTINIT	System trace not in state initialized
	TRC_NOTTRACE	Invalid trace pointer
	TRC_SUCCESS	Success

TRC_correlateTime() samples wall clock time and CPU timebase register time (as quickly as it can manage), and stores the results in the indicated trace buffer. The intent is that the timebase register times captured by the trace can be converted later to wall clock time.

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

Parameters:

	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)

Return values:

	TRC_ALLOCMEM	Cannot allocate memory
	TRC_PARMNULL	NULL parameter detected
	TRC_NOTINIT	System trace not in state initialized
	TRC_SUCCESS	Success

TRC_create() creates and initializes a user trace buffer.

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.

Parameters:

trc

(in) Trace buffer handle

Return values:

	TRC_NOSYSDEL	Cannot delete the system trace
	TRC_NOTTRACE	Not a vlid trace pointer
	TRC_SUCCESS	Success

TRC_delete() deletes a user trace buffer

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.

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

unsigned int TRC_differMonitor	(	TRC_Monitor *	old,
		TRC_Monitor *	new,
		TRC_Top *	top
	)

Take the difference between monitor snapshots.

Parameters:

	old	(in) Record at start of sampling period
	new	(in) Record at end of sampling period
	top	(out) Differential monitor record

Return values:

	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

TRC_differMonitor() knows how to take the "difference" between two monitor records and place a summary in the output TRC_Top structure.

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.

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

WCT_time_sat TRC_getTopTime

(

TRC_Top *

top

)

Get the timestamp from a differential monitor record.

Parameters:

top

(in) Differential monitor record

Return values:

	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.

Parameters:

	id	(in) Trace identification number (user defined)
	trc	(out) Trace buffer handle

Return values:

	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.

Parameters:

	rows	(in) Number of rows in system trace buffer (default 1024)
	enable	(in) System trace elements to enable

Return values:

	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

TRC_initialize() builds up the trace facilities

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.

Parameters:

	nam	(in) Trace name (user defined)
	trc	(out) Trace buffer handle

Return values:

	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.

Parameters:

	trc	(in) Trace buffer to use (NULL => "system" trace buffer)
	fui	(in) Record format
	dat	(in) Record data (always 6 longwords = 24 bytes)

Return values:

x

The timestamp captured from the CPU time-base register

TRC_record() records a row in a trace buffer.

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.

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.

FORK_que * TRC_setFork

(

FORK_que *

fqi

)

Convert a trace name to a trace buffer pointer.

Parameters:

fqi

(in) Set the fork queue trace should use for snapshots

Returns:

Previous value of fork queue

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.

Return values:

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.

Return values:

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

Parameters:

trc

(in) Trace buffer (NULL => system trace)

Return values:

	0	Cannot locate trace buffer
	x	Size of a complete trace buffer

A complete trace buffer is a contiguous piece of memory consisting of a trace buffer (a TRC_Buffer structure, also with some padding) and a common area (a TRC_Common structure, with some padding) . The padding has to do with the requirement that certain elements in these structures must be cache line aligned on a PowerPC architecture.

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.

Parameters:

mon

(out) Where to put the results

Return values:

	TRC_PARMNULL	NULL parameter detected
	TRC_NOTINIT	Trace system not in state initialized
	TRC_SUCCESS	Success

TRC_snapMonitor() copies the current monitor contents of the task to name table to a lookaside monitor buffer.

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.

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.

int TRC_tdb2tid

(

int

tdb

)

Translate a task ID (CPU_DB/ITC style) to a VxWorks task ID.

Parameters:

tdb

(in) Task ID (CPU_DB/ITC definition) (0 => "self")

Return values:

	0	No translation available
	x	VxWorks task ID

TRC_tdb2tid() translates a task ID in the numbering scheme defined by CPU_DB and ITC to a VxWorks task ID (really a pointer to a WIND_TCB structure). This only works on embedded systems, and will return zero on host systems.

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.

Parameters:

	trc	(in) The buffer handle
	fil	(in) File name

Warning:

It is potentially fatal to call this routine on a "hot" trace (i.e. a trace that may have new rows added while this routine is executing). It is left to the caller of this routine to ensure this pre-condition is met (by locking the task, or better still, using the snapshot facilities).

TRC_write() writes a trace buffer to a file.

References _TRC_Buffer::frame, _TRC_Common::size, _TRC_Buffer::size, and TRC_M_BUFFER.

Referenced by TRC_sendFile().