Generic Trace Support

The "Generic Tracing" module. Provides producers of content the ability to, in a runtime-independant way, add tracing. Also provides consumers of trace-enabled content the mechanisms necessary to enable/disable the various trace statements. More...

Data Structures
struct	GT_Mask
	Object representing a GT module instance. More...
Defines
#define	GT_ENTER ((UInt8)0x01)
	Mask for tracing entry and exit points within functions.
#define	GT_1CLASS ((UInt8)0x02)
#define	GT_2CLASS ((UInt8)0x04)
#define	GT_3CLASS ((UInt8)0x08)
#define	GT_4CLASS ((UInt8)0x10)
#define	GT_5CLASS ((UInt8)0x20)
	User mask 5. By convention, used for benchmarking related tracing.
#define	GT_6CLASS ((UInt8)0x40)
	User mask 6. By convention, used for internal warning related tracing.
#define	GT_7CLASS ((UInt8)0x80)
	User mask 7. By convention, used for internal error related tracing.
#define	GT_create(mask, modName) _GT_create((mask), (modName))
#define	GT_set(str) _GT_set(str)
#define	GT_0trace(mask, classId, format)
#define	GT_1trace(mask, classId, format, arg1)
#define	GT_2trace(mask, classId, format, arg1, arg2)
#define	GT_3trace(mask, classId, format, arg1, arg2, arg3)
#define	GT_4trace(mask, classId, format, arg1, arg2, arg3, arg4)
#define	GT_5trace(mask, classId, format, arg1, arg2, arg3, arg4, arg5)
#define	GT_6trace(mask, classId, format, arg1, arg2, arg3, arg4, arg5, arg6)
Functions
Void	_GT_create (GT_Mask *mask, String modName)
	Initialize a GT mask.
Void	GT_init (Void)
	Initialize the GT module.
Void	_GT_set (String str)
	Modify the current trace mask settings.
Int	_GT_trace (GT_Mask *mask, Int classId, String format,...)
	Conditionally emit a trace statement.

Detailed Description

The "Generic Tracing" module. Provides producers of content the ability to, in a runtime-independant way, add tracing. Also provides consumers of trace-enabled content the mechanisms necessary to enable/disable the various trace statements.

Remarks:: Note that the public APIs (e.g. GT_create()) are implemented as macros around private services of a similar name, but prefixed with an underscore (e.g. _GT_create()). This enables GT tracing to be conditionally compiled out of code bases. Users of the GT APIs should never call the private services (indicated by convention with a leading underscore '_'). Rather, they should restrict usage to the public APIs (i.e., call GT_1trace(), not _GT_trace()).

Define Documentation

#define GT_ENTER ((UInt8)0x01)

Mask for tracing entry and exit points within functions.

#define GT_1CLASS ((UInt8)0x02)

User mask 1.

#define GT_2CLASS ((UInt8)0x04)

User mask 2.

#define GT_3CLASS ((UInt8)0x08)

User mask 3.

#define GT_4CLASS ((UInt8)0x10)

User mask 4.

#define GT_5CLASS ((UInt8)0x20)

User mask 5. By convention, used for benchmarking related tracing.

#define GT_6CLASS ((UInt8)0x40)

User mask 6. By convention, used for internal warning related tracing.

#define GT_7CLASS ((UInt8)0x80)

User mask 7. By convention, used for internal error related tracing.

#define GT_create	(	mask,
		modName		)	_GT_create((mask), (modName))

Initialize a GT mask.

Parameters:

`[in]`	mask	Address of an existing GT_Mask structure.
`[in]`	modName	Module name to be associated with this mask.

Precondition:: mask must point to a pre-allocated GT_Mask structure. Typically this memory is set aside as a static global variable for simplicity, althought that need not be the case.

Remarks:: This function should not be called directly. Users should use the GT_create() macro wrapping this function instead, to enable conditional removal of tracing from the client binaries.; modName must be unique within the entire system. To that end, it typically contains the client package's name.

#define GT_set ( str ) _GT_set(str)

Modify the current trace mask settings.

Parameters:

[in] str New trace format string.

Remarks:: _GT_set() should not be called directly. Users should use the GT_set() macro which wraps _GT_set() instead, to enable conditional removal of tracing from the client binaries.

#define GT_0trace	(	mask,
		classId,
		format	)

Value:

((*(mask).flags & (classId)) ? \
    _GT_trace(&(mask), (classId), (format)) : 0)

See also:: _GT_trace()

#define GT_1trace	(	mask,
		classId,
		format,
		arg1	)

Value:

((*(mask).flags & (classId)) ? \
    _GT_trace(&(mask), (classId), (format), (arg1)) : 0)

See also:: _GT_trace()

#define GT_2trace	(	mask,
		classId,
		format,
		arg1,
		arg2	)

Value:

((*(mask).flags & (classId)) ? \
    _GT_trace(&(mask), (classId), (format), (arg1), (arg2)) : 0)

See also:: _GT_trace()

#define GT_3trace	(	mask,
		classId,
		format,
		arg1,
		arg2,
		arg3	)

Value:

((*(mask).flags & (classId)) ? \
    _GT_trace(&(mask), (classId), (format), (arg1), (arg2), (arg3)) : 0)

See also:: _GT_trace()

#define GT_4trace	(	mask,
		classId,
		format,
		arg1,
		arg2,
		arg3,
		arg4	)

Value:

((*(mask).flags & (classId)) ? \
    _GT_trace(&(mask), (classId), (format), (arg1), (arg2), (arg3), (arg4)) : 0)

See also:: _GT_trace()

#define GT_5trace	(	mask,
		classId,
		format,
		arg1,
		arg2,
		arg3,
		arg4,
		arg5	)

Value:

((*(mask).flags & (classId)) ? \
    _GT_trace(&(mask), (classId), (format), (arg1), (arg2), (arg3), (arg4), (arg5)) : 0)

See also:: _GT_trace()

#define GT_6trace	(	mask,
		classId,
		format,
		arg1,
		arg2,
		arg3,
		arg4,
		arg5,
		arg6	)

Value:

((*(mask).flags & (classId)) ? \
    _GT_trace(&(mask), (classId), (format), (arg1), (arg2), (arg3), (arg4), \
        (arg5), (arg6)) : 0)

See also:: _GT_trace()

Function Documentation

Void _GT_create	(	GT_Mask *	mask,
		String	modName
	)

Initialize a GT mask.

Parameters:

`[in]`	mask	Address of an existing GT_Mask structure.
`[in]`	modName	Module name to be associated with this mask.

Precondition:: mask must point to a pre-allocated GT_Mask structure. Typically this memory is set aside as a static global variable for simplicity, althought that need not be the case.

Remarks:: This function should not be called directly. Users should use the GT_create() macro wrapping this function instead, to enable conditional removal of tracing from the client binaries.; modName must be unique within the entire system. To that end, it typically contains the client package's name.

Void GT_init ( Void )

Initialize the GT module.

Remarks:: GT_init() can be called multiple times, and should be called by all explicit users of GT.

Void _GT_set ( String str )

Modify the current trace mask settings.

Parameters:

[in] str New trace format string.

Remarks:: _GT_set() should not be called directly. Users should use the GT_set() macro which wraps _GT_set() instead, to enable conditional removal of tracing from the client binaries.

Int _GT_trace	(	GT_Mask *	mask,
		Int	classId,
		String	format,
			...
	)

Conditionally emit a trace statement.

Parameters:

`[in]`	mask	Mask associated with this trace statement.
`[in]`	classId	class of this trace statement.
`[in]`	format	printf-style format string.

Remarks:: This function should not be called directly. Users should use the macros wrapping this function instead (e.g. GT_1trace()) to enable conditional removal of tracing from the client binaries.; classId can be a logically OR'd set of classes. Doing so will cause the trace to be emitted if any of the classId classes are enabled in the current settings of the mask.; Most, but not all printf format strings are supported.

Precondition:: mask must have been initialized with GT_create().

See also:: GT_create()

Generic Trace Support

Data Structures

Defines

Functions

Detailed Description

Define Documentation

Function Documentation