Trace-Based Debugging

Kernel debug messages

KTRACE

During development, drivers can display information for debugging purposes. The basic API to use for this is Kern::Printf().

You can make the display of debugging messages conditional on whether certain flags have been set in the ROM. To do this, use the print command with the __KTRACE_OPT() macro. For example:

_KTRACE_OPT(KDEVICE,Kern::Printf("++DExDriverLogicalChannel::DoCreate"));

This macro's first argument is a mask that must be enabled for the message to be displayed. The kerneltrace keyword, defined in header.iby, sets which masks are enabled for a debug ROM image.

The following are some of the mask definitions that can be found in nk_trace.h:

• KHARDWARE

• KEXTENSION

• KDMA

• KBOOT

• KSCRATCH

• KPANIC

• KPBUS1

• KPBUS2

BTrace service

BTrace is a Kernel service that is designed to generate and capture trace information with minimal impact on a running system. It is useful for generating trace information in the Kernel and in drivers, for which fast tracing is required and general serial debug is not possible.

BTrace defines API and macros to use in programs to create trace information in e32btrace.h. The generated trace messages can be retrieved from the driver or Kernel during execution. To do this, BTrace must be built into the ROM image; it is included by default in a text shell ROM. The BTrace command should then be executed from the text shell with the appropriate options. For example, the following commands sets various filter and buffer size options, runs a program called t_expio that generates some trace data, and finally writes the trace data into a file d:\expiolog.txt.

BTRACE -f1,2,3 -m3 -b1024
t_expio.exe
BTRACE d:\expiolog.txt

The basic macros used for generating traces are:

• BTrace0 (aCategory,aSubCategory)

• BTrace4 (aCategory,aSubCategory,a1)

• BTrace8 (aCategory,aSubCategory,a1,a2)

• BTrace12(aCategory,aSubCategory,a1,a2,a3)

The macros set category and sub-category values with their first two arguments. The category indicates the type of information being recorded, which is specified using a value from the enumeration BTrace::TCategory. The sub-category is an enumeration specific to each category. The other arguments, a1 -a3, set the trace data, of lengths 0, 4, 8 or 12 bytes, to record.

For longer traces that include a context ID, program counter values, and different filters, more macros are provided. Performance logging macros are also available which in turn use BTrace to log performance related data. For example:

TKName nameBuf;
Name(nameBuf);

// Output a fast-trace record of the specified category which also 
// includes a Context ID 
BTraceContextN(BTrace::EChunks,BTrace::EChunkCreated,this,iMaxSize,
    nameBuf.Ptr(),nameBuf.Size());