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:

1. Create and set a trace filter.

2. Read trace data from kernel side chunks.

3. Write trace data to the user side buffers.

4. 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();
    }