UTrace API

This topic lists the various functionality changes in the UTrace API for UTF 2.0. It covers the following sub-topics:

Trace Calls

In UTF 1.0, all trace calls are contained in the TUTrace class and you can instantiate a TUTrace object. The TUTrace object sets some values, which are used when the trace functions are called. Alternatively, you can pass these values as parameters into each trace call.

In UTF 2.0, all trace calls are defined as global static functions which do not belong to a class. Instead of using values stored in a TUTrace object each trace function takes a TTraceContext as a parameter. The TTraceContext class has constructors that set default values for the following parameters:

Parameter Default Value

ModuleUid

TTraceContext::DefaultModuleUid();

Normally, it is UID3 of an application.

Note: To override the default ModuleUid, you can use EXECUTABLE_DEFAULT_MODULEUID, which is defined in e32utrace_basic_types.h.

Thread Identification

EAddThreadIdentification

Note: To override the default setting for adding or not adding the thread identification in a trace packet, you can use EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION.

Program Counter

ENoProgramCounter

Note: To override the default setting for adding or not adding the program counter in a trace packet, you can use EXECUTABLE_DEFAULT_HAS_PC.

The following code snippets explain how to override the default values:

MMP file

- -#define SYMBIAN_INCLUDE_EXECUTABLE_TRACE -//override the default values -MACRO EXECUTABLE_DEFAULT_MODULEUID=0x00210D3B -MACRO EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION=ENoThreadIdentification -MACRO EXECUTABLE_DEFAULT_HAS_PC=EAddProgramCounter -#include <e32utrace.mmh> - -

CPP file

#include <e32utrace.h> -using namespace UTF; - -void e32main() -{ - - // print the trace using default ModuleUid, ThreadIdentification and ProgramCounter settings - Printf(TTraceContext(EBorder), “File handle is %s.”, iMyData); - - // do a binary trace - FormatId myDataFormat = KInitialClientFormat; //KInitialClientFormat as defined in e32utrace_basic_types.h - Trace(TTraceContext(EBorder), myDataFormat, iMyData, sizeof(iMyData)); // data to be included in the trace output - - // override the default context values - TModuleUid useCaseA = 0x00210D3C; - Trace(TTraceContext(useCaseA, EBorder, ENoThreadIdentification, ENoProgramCounter), myDataFormat, iMyData, sizeof(iMyData)); + + + + + +UTrace API

This topic lists the various functionality changes in the UTrace API for UTF 2.0. It covers the following sub-topics:

API Changes
Trace Calls
Exported Traces
Trace Points
Identifiers

API Changes

The following table lists the various changes in the UTrace API for UTF 2.0:

Item UTF 1.0 UTF 2.0

Namespace

Not supported

UTF

Class containing trace methods

TUTrace

TTraceContext

8-bit filter and identifier

TUint8 TPrimaryFilter

TUint8 TClassification

32-bit filter and identifier

TUint32 TSecondaryFilter

TUint32 TModuleUid

8-bit identifier

TUint8 TTraceSchema

Not supported

16-bit identifier

Not supported

TUint16 TFormatId

Context ID

TBool aIncludeContextId

enum THasThreadIdentification +{ + EAddThreadIdentification = ETrue, + ENoThreadIdentification = EFalse +}; +

Program Counter

TBool aIncludePc

enum THasProgramCounter +{ + EAddProgramCounter = ETrue, + ENoProgramCounter = EFalse +}; +

Trace Calls

Parameter Default Value

ModuleUid

TTraceContext::DefaultModuleUid();

Normally, it is UID3 of an application.

Note: To override the default ModuleUid, you can use EXECUTABLE_DEFAULT_MODULEUID, which is defined in e32utrace_basic_types.h.

Thread Identification

EAddThreadIdentification

Note: To override the default setting for adding or not adding the thread identification in a trace packet, you can use EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION.

Program Counter

ENoProgramCounter

Note: To override the default setting for adding or not adding the program counter in a trace packet, you can use EXECUTABLE_DEFAULT_HAS_PC.

The following code snippets explain how to override the default values:

MMP file

+ +#define SYMBIAN_INCLUDE_EXECUTABLE_TRACE +//override the default values +MACRO EXECUTABLE_DEFAULT_MODULEUID=0x00210D3B +MACRO EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION=ENoThreadIdentification +MACRO EXECUTABLE_DEFAULT_HAS_PC=EAddProgramCounter +#include <e32utrace.mmh> + +

CPP file

#include <e32utrace.h> +using namespace UTF; + +void e32main() +{ + + // print the trace using default ModuleUid, ThreadIdentification and ProgramCounter settings + Printf(TTraceContext(EBorder), “File handle is %s.”, iMyData); + + // do a binary trace + FormatId myDataFormat = KInitialClientFormat; //KInitialClientFormat as defined in e32utrace_basic_types.h + Trace(TTraceContext(EBorder), myDataFormat, iMyData, sizeof(iMyData)); // data to be included in the trace output + + // override the default context values + TModuleUid useCaseA = 0x00210D3C; + Trace(TTraceContext(useCaseA, EBorder, ENoThreadIdentification, ENoProgramCounter), myDataFormat, iMyData, sizeof(iMyData)); }

Note: In UTF 1.0, you must specify whether to send a trace using only a primary filter or a combination of primary and secondary filters. You must also set up Context ID and Program counter for each trace.

Exported Traces

In UTF 1.0, the e32btrace.h header file needs to be included in source for the trace calls.

In UTF 2.0, trace calls can be exported. To export the trace calls, you must include the e32utrace.h header file in the source and the e32utrace.mmh file in an MMP file. If you want to include trace data in ROM, then use the implemented version of the utraceuser.dll. To disable all traces in the entire ROM, replace the implemented DLL with the stubbed DLL called utraceuserstubbed.dll. This allows you to choose a stubbed version over an implemented version without recompiling all components at ROM build time.

Trace Points

In UTF 1.0, the #define SYMBIAN_TRACE_ENABLE must be defined in an MMP file if traces are to be compiled into source code. In UTF 2.0, the following define statement is added instead of #define SYMBIAN_TRACE_ENABLE:

#define SYMBIAN_INCLUDE_EXECUTABLE_TRACE

This must be defined in your MMP file to implement the traces in source.

Identifiers

In UTF 2.0, the TTraceSchema (8-bit identifier) is removed and TFormatId (16-bit identifier) added in its place. The TFormatId identifier is used in conjunction with the Classification and the ModuleUid. It describes how the trace records are to be parsed on the host side.

There are two pre-defined FormatIds, KFormatIdPrintf and KFormatIdPrintfUnicode, which differentiate between normal and unicode printf calls. These two pre-defined ids are sent as part of a trace packet generated by a call to any of the printf calls.

\ No newline at end of file