#include "tm.h"
Void
TM_INIT()
QU_Head *
TM_GETHEAD()
SuccFail
TM_CONFIG(char *pFileName)
Void
TM_OPEN(tm_ModInfo *hModCB, char *modName)
Void
TM_TRACE(args)
Bool
TM_QUERY(tm_ModInfo *modInfo, TM_Mask mask)
SuccFail
TM_VALIDATE()
Int
TM_SETUP(char *args)
LgInt
TM_HEXDUMP(hModCB, bits, msg, pdu, len)
Void
TM_CALL(hModCB, bits, pFunc, hParam1, hParam2)
For backwards compatibility:
Void
TM_init(void);
QU_Head *
TM_getHead(void);
SuccFail
TM_config(Char *tmFileName);
tm_ModInfo *
TM_open(Char *moduleName);
SuccFail
TM_setMask(Char *moduleName, TM_Mask moduleMask);
Bool
tm_trace(tm_ModInfo *modInfo, TM_Mask mask, Char *format, ...);
Bool
TM_query(tm_ModInfo *modInfo, TM_Mask mask);
SuccFail
TM_validate(void);
Int
TM_setUp(Char * str);
LgInt
TM_hexDump(tm_ModInfo *modInfo, TM_Mask mask, String str,
unsigned char *address, Int length);
Void
TM_call(tm_ModInfo *modInfo,
TM_Mask mask,
void (* pfCallMe)(void * hParam1, void * hParam2),
void * hParam1,
void * hParam2);
The Trace Module (TM_) selectively and dynamically generates trace messages in order to facilitate program debugging. Within OCP, each module may have its own particular degree of TM_ tracing enabled at run-time. Developers may also use TM_ tracing within applications in a similar manner.
Use of the Trace Module has several advantages over other traditional tracing methods such as printf() statements:
Tracing may also be globally enabled or disabled at compile time without performing any changes to the source code, other than changing the value of a defined value in a single include file. This allows fully debugged programs to occupy minimal space.
The specific actions actually performed by each of the TM_ facilities may be altered by the integrator depending upon the availability of the operating environment facilities. For instance time stamping may not be available on systems lacking a time-of-day facility.
IMPORTANT NOTE:
The public interface to the Trace Module, as presently defined, consists of a set of all-upper-case macros. The mixed-case function calls are included here for backwards compatibility only and should not be used for new applications.
The macro interface contains hidden #ifdef TM_ENABLED preprocessor
directives, thereby eliminating the need to bracket each and every
reference to TM_ module facilities with conditional compilation
directives. This way, for those applications that require minimal
memory usage, the Trace Module can be eliminated entirely by undefining
TM_ENABLED in oe.h.
Void TM_INIT() QU_Head * TM_GETHEAD() SuccFail TM_CONFIG(char *pFileName) SuccFail TM_VALIDATE()
Global initialization of TM_ is performed by TM_INIT(), which should be called once at the start of a user program and prior to any other TM_ facilites. TM_INIT() creates two queues of trace module information - an active queue and a setup queue. All information about TM_ users is entered in these queues.
Use TM_CONFIG() to redirect TM_ output to a device or file other than stdout.
TM_VALIDATE() searches the setup queue for the names of invalid TM_ user modules and deletes them from the queue.
Int TM_SETUP(char *args) Void TM_OPEN(tm_ModInfo *hModCB, char *modName)
Independent module tracing functionalities may be selected by creating tracing modules through the TM_SETUP() and TM_OPEN() facilities. Within each TM_ user module 16 different tracing types may be selected. Each type is specified by a bit within a bit mask. Trace types range from 0x0000 to 0xffff.
The type of trace information to be displayed, is defined by the owner of the module with the exception of trace type 0 (TM_ENTER). Trace type (TM_ENTER) is by convention used for external function entry tracing.
The criteria for displaying the trace information is that the bitwise and (&) result of the trace statement's mask and the dynamic tracing mask associated with that module is non-zero.
TM_SETUP() reads an argument list of the form "MODULE_NAME,BITMASK"
and enters the module name and bit mask in either the setup queue or
the active queue.
If an associated user module has not yet registered itself with TM_ via
a call to TM_OPEN(), then a new trace module information entry is made
in the setup queue.
Otherwise, the information goes in an exisiting entry in the active queue.
For example, if
args equals "G_,ffff" then a queue entry will be made in which the G_
module is assiged the bit mask 0xffff. If the G_ module has not yet registered
itself, then this information will go in the setup queue. Otherwise it will
go in the active queue.
TM_OPEN() creates a new trace module information entry in the active queue. modName is assigned to the entry's module name member. It's bit mask setting is determined by the state of the setup queue. If there exists an entry in the setup queue with the same module name (typically made by a call to TM_SETUP), then the mask is taken from that queue. Otherwise the mask is set to zero (tracing disabled).
TM_OPEN() returns a pointer to the new entry in the active queue in hModCB.
TM_TRACE(args)
Trace messages are generated by the TM_TRACE() facility, which accepts an argument list string and a variable number of associated arguments.
The following code fragment demonstrates the usage of the Trace Module.
Click here to see the complete codes.
In the previous example, if you wished to enable trace options for a module, you would specify, on the command line, the following:
-T <module_name>,<hex_bits>
where <module_name> is a valid OCP module, i.e. SCH_, TMR_, etc, and <hex_bits> is a hexidecimal value (without a leading "0x") specifying which trace bits for that module to enabled.
Multiple sets of -T options may be specified to enable tracing for more than one module.
For example:
ops_xmpl -T UDP_,ffff -T IMQ_,3
General usage dictates that lower-order bits produce less output. The lowest-order bits are often useful even during normal operation of the application. Bits above the first byte are reserved for trace options that provide a lot of output, such as dumping of complete PDUs.
The actual format of a Trace Module output may vary between implementations. The following example, however, is typical of many hosted systems. Each trace contains the source file name and line number from which the trace was generated, followed by a variable number of user data fields. For example:
clinvktd.c, 197: fsm_ePass: machine=0x60e38 evtId=0x8