TRC_control.c File Reference

Control functions for the TRC package. More...

#include <ctype.h>
#include <string.h>
#include <PBS/CACHE.h>
#include <PBS/MBA.h>
#include <PBS/PTS.h>
#include <PBS/RW.ih>
#include <PBS/MTX.h>
#include <MDB/MDB_pubdefs.h>
#include <TRC/TRC_msgs.h>
#include <TRC/TRC_pubdefs.h>
#include <TRC_prvdefs.h>

Defines
#define	TRC_L_SEED   (3)
	Length of the task name seed table.
Functions
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.
FORK_que *	TRC_setFork (FORK_que *fqi)
	Convert a trace name to a trace buffer pointer.
unsigned int	TRC_validTrace (TRC_Control *tcb, TRC_Buffer **trc)
	Validate a trace pointer (plus trace initialization...).
Variables
TRC_Control *	TRC_tcb
	Pointer to trace control block (initialized to NULL).
static char *	s_seed [TRC_L_SEED] = { "UND>", "EX5>", "EX9>" }
	Array of task seed names.
static char *	s_system = "system"
	Array of task seed names.

---

Detailed Description

Control functions for the TRC package.

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

Author:

A.P.Waite

TRC_control.c provides facilities to initialize the TRC trace system. These are the very basic trace facilities and require very little in the way of resources (other than large quantities of memory). The goal is to have this package exist at such a low level in the package hierarchy that nearly all other packages can call the TRC_record() function.

Warning:

Suitable task switch 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_record() calls.

---

Function Documentation

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.

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_validTrace	(	TRC_Control *	tcb,
		TRC_Buffer **	trc
	)

Validate a trace pointer (plus trace initialization...).

Parameters:

	tcb	(in) Trace control block
	trc	(in) Trace buffer handle (doubly indirect!)

Return values:

	TRC_NOTINIT	Trace system not in state initialized
	TRC_NOTTRACE	Not a trace buffer
	TRC_SUCCESS	Success

TRC_validTrace() runs a standard validation on a trace buffer pointer. Success indicates that the control block is valid, the trace buffer pointer is valid (and may have been substituted with the system trace buffer pointer if the buffer pointer was originally NULL).

References _TRC_Control::nxt, _TRC_Control::state, TRC_CTL_INITIALIZED, and TRC_M_BUFFER.

Referenced by TRC_advertise(), TRC_attachSnap(), TRC_copy(), TRC_correlateTime(), TRC_delete(), TRC_detachSnap(), TRC_sizeofTrace(), and TRC_snapTrace().