TRC_trace.c File Reference

Facilities to insert records into a trace. More...

#include <ctype.h>
#include <string.h>
#include <fcntl.h>
#include <unistd.h>
#include <PBI/Endianness.h>
#include <CPU_DB/CPU_DB_pubdefs.h>
#include <FBS/FBS_pubrtos.h>
#include <MDB/MDB_pubdefs.h>
#include <PBS/CACHE.h>
#include <PBS/MBA.h>
#include <PBS/PTS.h>
#include <PBS/RW.ih>
#include <TRC/TRC_msgs.h>
#include <TRC_prvdefs.h>

Functions

static void recover (TRC_Buffer *trc)

Try to recover if the row pointers are messed up.

static unsigned int validName (const char *name, const char *func)

Validate a trace name.

static __inline void record (TRC_Buffer *trc, unsigned long long tim, unsigned int fui, unsigned int *dat)

Insert a record in the trace (worker bee).

unsigned int TRC_advertise (TRC_Buffer *trc)

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

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 long long TRC_record (TRC_Buffer *trc, unsigned int fui, unsigned int *dat)

Insert a record into a trace.

unsigned int TRC_sizeofTrace (TRC_Buffer *trc)

Return the size of a complete compound trace (buffer plus common).

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.

Variables

static const char s_noData [TRC_DATA_ROW_SIZE<< 2]

Data recorded when the user specifies a NULL data pointer.

static const char s_misaligned [TRC_DATA_ROW_SIZE<< 2]

Data recorded when the user specifies a misaligned data pointer.

const char * TRC_noData = s_noData

External pointer to the fixed "no data" string.

const char * TRC_misaligned = s_misaligned

External pointer to the fixed "data misaligned" string.

Detailed Description

Facilities to insert records into a trace.

CVS $Id: TRC_trace.c,v 1.6 2011/03/29 00:59:53 apw Exp $

Author:: A.P.Waite

TRC_trace.c provides facilities to insert records into trace

Warning:

Suitable task switch tracing facilities are not available on host systems. Hosts can however build trace buffers with calls to TRC_record().

Function Documentation

static __inline void record	(	TRC_Buffer *	trc,
		unsigned long long	tim,
		unsigned int	fui,
		unsigned int *	dat
	)			`[static]`

Insert a record in the trace (worker bee).

Parameters:

	trc	(in) Trace buffer to use
	tim	(in) Timestamp (value from CPU's timebase register)
	fui	(in) Record format (as unsigned int)
	dat	(in) Record data (always 6 longwords, must long word aligned)

record() is a worker bee for all calls wishing to put records in the trace. It's a purely intenal routine and takes advantage of that to make a few assumptions:

The caller has already taken care of interlocking this operation
trc has already been validated
tim contains a valid timestamp taken from the CPU timebase register
dat is long word aligned and is a viable pointer to 24 bytes

References _TRC_Buffer::count, _TRC_Row::dat, _TRC_Buffer::first, _TRC_Row::fui, _TRC_Buffer::last, _TRC_Buffer::max, _TRC_Buffer::min, _TRC_Buffer::row, and _TRC_Row::tics.

Referenced by TRC_record().

static void recover ( TRC_Buffer * trc ) [static]

Try to recover if the row pointers are messed up.

Parameters:

trc

(in) Trace buffer to recover

recover() tries to use knowledge about how trace buffers are contructed to recover from corrupted row pointers.

References _TRC_Buffer::max, _TRC_Buffer::min, _TRC_Buffer::rec, _TRC_Buffer::row, _TRC_Buffer::rows, _TRC_Buffer::size, TRC_CACHE_LINE_PAD, TRC_L_ROWS_MAX, and TRC_L_ROWS_MIN.

Referenced by TRC_record().

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

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

static unsigned int validName	(	const char *	name,
		const char *	func
	)			`[static]`

Validate a trace name.

Parameters:

	name	(in) Trace name
	func	(in) Name of calling routine

Return values:

	TRC_NAMELEN	Trace name length out of valid range
	TRC_NAMENULL	Trace name is a NULL pointer
	TRC_NAMESNTX	Trace name has invalid syntax
	TRC_SUCCESS	Success

TRC_validName() validates a trace name.

References TRC_L_TRACENAME.

Referenced by TRC_create().

Variable Documentation

static const char s_misaligned[TRC_DATA_ROW_SIZE<< 2] [static]

Initial value:

    { TRC_DAT_MISALIGN }

Data recorded when the user specifies a misaligned data pointer.

static const char s_noData[TRC_DATA_ROW_SIZE<< 2] [static]

Initial value:

    { TRC_DAT_NODATA }

Data recorded when the user specifies a NULL data pointer.


Functions
static void	recover (TRC_Buffer *trc)
	Try to recover if the row pointers are messed up.
static unsigned int	validName (const char name, const char func)
	Validate a trace name.
static __inline void	record (TRC_Buffer trc, unsigned long long tim, unsigned int fui, unsigned int dat)
	Insert a record in the trace (worker bee).
unsigned int	TRC_advertise (TRC_Buffer *trc)
	Use a MSG to advertise the location of the system trace blob.
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 long long	TRC_record (TRC_Buffer trc, unsigned int fui, unsigned int dat)
	Insert a record into a trace.
unsigned int	TRC_sizeofTrace (TRC_Buffer *trc)
	Return the size of a complete compound trace (buffer plus common).
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.
Variables
static const char	s_noData [TRC_DATA_ROW_SIZE<< 2]
	Data recorded when the user specifies a NULL data pointer.
static const char	s_misaligned [TRC_DATA_ROW_SIZE<< 2]
	Data recorded when the user specifies a misaligned data pointer.
const char *	TRC_noData = s_noData
	External pointer to the fixed "no data" string.
const char *	TRC_misaligned = s_misaligned
	External pointer to the fixed "data misaligned" string.