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