Generic Trace Support

---

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

Data Structures
struct	GT_Mask
	Object representing a GT module instance. More...
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.

---

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

---

Copyright 2008, Texas Instruments Incorporated