Kernel +Trace Tool Tutorial

Intended audience

This document is intended for +application developers writing a trace tool using the kernel trace tool component.

Required background

A knowledge of the filters defined +in EUser.

Introduction

The kernel trace tool is the user side +part of the kernel trace tool component. It provides output to trace tools +such as the command line kernel trace tool.

Using Kernel Trace Tool

The following tasks will +be covered in this tutorial:

Reading trace data from +chunks.
Writing trace data to +buffers.
Setting trace filters.
Requesting data notification.

To perform each of these tasks you must include db32trace.h and declare +an RBTrace object.

Basic procedure

The high level steps to using the +kernel trace filter are shown here:

Create and set a trace +filter.
Read trace data from +kernel side chunks.
Write trace data to +the user side buffers.
Request data notification.

Suggested structure

The functions described must +be called in sequence and some of them must be called more than once to read +all the trace data from the buffer. You are recommended to proceed as follows.

Create an RBTrace object +and call its Open() function.
Create a loop which +runs for as long as requests for notification of new data return successfully.
Create an inner loop +which runs for as long as read operations return data from the buffer.
Within the inner loop +call a function to do something with the data such as write it to a file.
Call the Close() function +of the RBTrace object.

It can be useful though it is not necessary to disable trace capture +while processing the data: you do this with calls to Mode() and SetMode().

+ RBTrace trace; + TInt error = trace.Open(); + if(error!=KErrNone) + return error; + const TInt KTraceDataBlockSize = 65536; // size of data we ideally want to process in one go + TUint8* data; + TInt size; + do + { + while((size=trace.GetData(data))!=0) + { + ProcessTheTraceData(data,size); + trace.DataUsed(); + } + TRequestStatus waitStatus; + trace.RequestData(waitStatus,KTraceDataBlockSize); + User::WaitForRequest(waitStatus); + error = waitStatus.Int(); + } + while(error==KErrNone); + trace.Close(); + return error; +

Command Line Kernel Trace Tool

The command line +kernel trace tool is supplied as a user interface to the kernel trace tool +and also as a reference implementation. It implements the inner loop by writing +trace data to file or to a debug port. Other possible implementations involve +writing the data to a fast connection off the device or to a graphics tool. +The command line kernel trace tool uses the filters defined in EUser: +it would also be possible to specify user defined filters.

+void Dump() + { + TUint oldMode = Trace.Mode(); + Trace.SetMode(0); // turn off trace capture while we dump + + TUint8* data; + TInt size; + while((size=Trace.GetData(data))!=0) + { + if(FileName) + { + TInt r=File.Write(TPtrC8(data,size)); + if(r!=KErrNone) + { + printf("Error writing to file (1). (Code %d)",r); + Error(); + } + } + if(DumpToDebugPort) + { + do + { + int s = size; + if(s>256) s=256; + RDebug::RawPrint(TPtrC8(data,s)); + data += s; + size -= s; + } + while(size); + } + Trace.DataUsed(); + } + // Flush the file here so we can be sure to detect whether the btrace data + // has been written successfully to the file. + TInt r = File.Flush(); + if (r != KErrNone) + { + printf("Error writing to file (2). (Code %d)",r); + Error(); + } + File.Close(); + + Trace.SetMode(oldMode); + RePrime(); + }