1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-0AB3D313-79FF-4716-AFD4-FF3AA3C2E936" xml:lang="en"><title>Trace-Based

    13 Debugging</title><shortdesc>This document describes how to generate traces with the Kernel

    14 Trace and BTrace APIs.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <section id="GUID-58E18DB3-8E47-4625-9F66-FEAEA3315587">       <title>Kernel

    16 debug messages</title><p><b>KTRACE</b> </p> <p>During development,

    17 drivers can display information for debugging purposes. The basic API to use

    18 for this is <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-CAAD1252-CBEF-318B-B61D-D12D4E80C5CF"><apiname>Kern::Printf()</apiname></xref>. </p> <p>You can make the display

    19 of debugging messages conditional on whether certain flags have been set in

    20 the ROM. To do this, use the print command with the <xref href="GUID-9C275309-15B4-34D0-AD05-44C6C501FC08.dita"><apiname>__KTRACE_OPT()</apiname></xref> macro.

    21 For example: </p> <codeblock id="GUID-BB56427E-762B-5B77-B3DA-369751A262D8" xml:space="preserve">_KTRACE_OPT(KDEVICE,Kern::Printf("++DExDriverLogicalChannel::DoCreate"));</codeblock> <p>This macro's first argument is a mask that must be enabled for the message

    22 to be displayed. The <codeph>kerneltrace</codeph> keyword, defined in <filepath>header.iby</filepath>,

    23 sets which masks are enabled for a debug ROM image. </p> <p>The following

    24 are some of the mask definitions that can be found in <filepath>nk_trace.h</filepath>: </p> <ul>

    25 <li id="GUID-3F091877-D335-5F73-A752-6D80E272D6E7"><p> <codeph>KHARDWARE</codeph>  </p> </li>

    26 <li id="GUID-CF060894-A381-5253-BA21-344DD6334E16"><p> <codeph>KEXTENSION</codeph>  </p> </li>

    27 <li id="GUID-BD44067A-0FCA-5C40-9F96-2996FAE96B4D"><p> <codeph>KDMA</codeph>  </p> </li>

    28 <li id="GUID-20E085C0-ECD6-5119-AC33-449D6F2EDA6C"><p> <codeph>KBOOT</codeph>  </p> </li>

    29 <li id="GUID-8221B2F2-6773-53DE-9784-EA609BA57900"><p> <codeph>KSCRATCH</codeph>  </p> </li>

    30 <li id="GUID-E395983C-A76B-5EC3-AA07-258074A0AE71"><p> <codeph>KPANIC</codeph>  </p> </li>

    31 <li id="GUID-AFCF4A79-C5E0-531C-97CE-A55F9BCE4E8C"><p> <codeph>KPBUS1</codeph>  </p> </li>

    32 <li id="GUID-A908027F-B8BC-54CC-B784-5FE45BA20E4F"><p> <codeph>KPBUS2</codeph>  </p> </li>

    33 </ul>     </section>

    34 <section id="GUID-B404E745-2D37-4D63-88D9-1ABAA474B58A"><title>BTrace service</title> <p>BTrace

    35 is a Kernel service that is designed to generate and capture trace information

    36 with minimal impact on a running system. It is useful for generating trace

    37 information in the Kernel and in drivers, for which fast tracing is required

    38 and general serial debug is not possible. </p> <p>BTrace defines API and macros

    39 to use in programs to create trace information in <filepath>e32btrace.h</filepath>.

    40 The generated trace messages can be retrieved from the driver or Kernel during

    41 execution. To do this, BTrace must be built into the ROM image; it is included

    42 by default in a text shell ROM. The <codeph>BTrace</codeph> command should

    43 then be executed from the text shell with the appropriate options. For example,

    44 the following commands sets various filter and buffer size options, runs a

    45 program called <filepath>t_expio</filepath> that generates some trace data,

    46 and finally writes the trace data into a file <filepath>d:\expiolog.txt</filepath>. </p> <codeblock id="GUID-F631555E-2736-5D57-9543-8566A22590B8" xml:space="preserve">BTRACE -f1,2,3 -m3 -b1024

    47 t_expio.exe

    48 BTRACE d:\expiolog.txt</codeblock> <p>The basic macros used for generating

    49 traces are: </p> <ul>

    50 <li id="GUID-C4CED603-6EAB-5CC3-8C8F-F72962F14F6D"><p> <codeph> BTrace0 (aCategory,aSubCategory)</codeph>  </p> </li>

    51 <li id="GUID-099F0EA6-60A2-50F7-B855-CC0DE97B70C2"><p> <codeph> BTrace4 (aCategory,aSubCategory,a1)</codeph>  </p> </li>

    52 <li id="GUID-1D643E7D-2C8B-51A1-B702-CA6BB644F61B"><p> <codeph> BTrace8 (aCategory,aSubCategory,a1,a2)</codeph>  </p> </li>

    53 <li id="GUID-B895DBA3-D4A2-59F7-952B-7E6E1856E1A4"><p> <codeph> BTrace12(aCategory,aSubCategory,a1,a2,a3)</codeph>  </p> </li>

    54 </ul> <p>The macros set category and sub-category values with their first

    55 two arguments. The category indicates the type of information being recorded,

    56 which is specified using a value from the enumeration <xref href="GUID-5BF17780-AD31-30CF-AFD9-915CBDA74441.dita#GUID-5BF17780-AD31-30CF-AFD9-915CBDA74441/GUID-E26B390F-390C-372B-B60F-9F788119A98B"><apiname>BTrace::TCategory</apiname></xref>.

    57 The sub-category is an enumeration specific to each category. The other arguments, <codeph>a1</codeph> -<codeph>a3</codeph>,

    58 set the trace data, of lengths 0, 4, 8 or 12 bytes, to record. </p> <p>For

    59 longer traces that include a context ID, program counter values, and different

    60 filters, more macros are provided. Performance logging macros are also available

    61 which in turn use BTrace to <xref href="GUID-9D26E38F-5C7B-5330-A54B-8F97D0F204D0-GENID-1-2-1-8-1-1-7-1-1-5-1.dita">log

    62 performance</xref> related data. For example: </p> <codeblock id="GUID-20F3E42A-B6F6-55B6-B0B5-D466518AC6DC" xml:space="preserve">TKName nameBuf;

    63 Name(nameBuf);

    64 

    65 // Output a fast-trace record of the specified category which also 

    66 // includes a Context ID 

    67 BTraceContextN(BTrace::EChunks,BTrace::EChunkCreated,this,iMaxSize,

    68     nameBuf.Ptr(),nameBuf.Size());</codeblock></section>

    69 </conbody></concept>