<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-9D26E38F-5C7B-5330-A54B-8F97D0F204D0" xml:lang="en"><title>Performance
Logging</title><shortdesc>Symbian platform provides macros that you can use in device driver
and kernel extension programs to write a trace log. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>You can use the trace log to test the performance of the programs. </p>
<section id="GUID-C332215D-B9E8-415B-8246-27D69F6A6E74"><title>Perfomance macros</title> <p>There are three macros that you
can insert into your code. They only differ with respect to the optional data
that you can add to the trace record. All are defined in <filepath>kernperfloger.h</filepath>  </p> <ul>
<li id="GUID-FB5EA9F3-4236-504C-B5A7-9FC1803A0DB8"><p> <xref href="GUID-0CBE2ABA-A508-3E26-88FE-E4DAAE945D5E.dita"><apiname>PERF_LOG0</apiname></xref> <codeph>(aSubCategory)</codeph>  </p> </li>
<li id="GUID-3B115481-BB41-55E3-AD33-225EB3B5A91C"><p> <xref href="GUID-226FB57A-414A-3DC8-BFD7-6B93B55CD4B1.dita"><apiname>PERF_LOG1</apiname></xref> <codeph>(aSubCategory,aUserData)</codeph> </p> </li>
<li id="GUID-FCBBFB1A-7DC9-5857-A0E0-050EA5C48FED"><p> <xref href="GUID-78D928F5-0ADA-31BE-A71D-0542A9B6E3D6.dita"><apiname>PERF_LOG2</apiname></xref> <codeph>(aSubCategory,aUserData,aUserData2)</codeph> </p> <p>Note:
the <xref href="GUID-02CF31A2-562D-3E8B-9A12-4C93D1B8DD19.dita"><apiname>PERF_LOG</apiname></xref> macro is identical to <xref href="GUID-78D928F5-0ADA-31BE-A71D-0542A9B6E3D6.dita"><apiname>PERF_LOG2</apiname></xref>. </p> </li>
</ul> <p>You must specify an the 8-bit integer subcategory value in the <codeph>aSubCategory</codeph> argument.
You can also supply one or two (or zero) 32-bit values; you are free to decide
on the meaning of such values. </p> <p>The macros wrap around the standard <codeph>BTrace***</codeph> macros.
All trace records generated by these macros are given a category of <xref href="GUID-5BF17780-AD31-30CF-AFD9-915CBDA74441.dita#GUID-5BF17780-AD31-30CF-AFD9-915CBDA74441/GUID-E0E36933-0D01-35A9-9CCE-015F28E7E386"><apiname>BTrace::EKernPerfLog</apiname></xref>. </p> <p>The
generation and capture of trace information is implemented as a kernel extension.
This means that it is loaded and activated at an early stage in the startup
process of the device. </p> </section>
<section id="GUID-AD31830B-ED00-436F-9B36-EB3B3B0BFE4F"><title>Performance macro output format</title> <p>The following table
shows which fields of a trace record are generated by each of the macros <xref href="GUID-0CBE2ABA-A508-3E26-88FE-E4DAAE945D5E.dita"><apiname>PERF_LOG0</apiname></xref>, <xref href="GUID-226FB57A-414A-3DC8-BFD7-6B93B55CD4B1.dita"><apiname>PERF_LOG1</apiname></xref>,
and <xref href="GUID-78D928F5-0ADA-31BE-A71D-0542A9B6E3D6.dita"><apiname>PERF_LOG2</apiname></xref>: </p> <table id="GUID-B409B220-479A-5999-A746-33787F764B6C">
<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
<tbody>
<row>
<entry><p> <b>Field</b>  </p> </entry>
<entry><p> <b>PERF_LOG0</b>  </p> </entry>
<entry><p> <b>PERF_LOG1</b>  </p> </entry>
<entry><p> <b>PERF_LOG2</b>  </p> </entry>
</row>
<row>
<entry><p>Fast Counter Timestamp </p> </entry>
<entry><p>Yes </p> </entry>
<entry><p>Yes </p> </entry>
<entry><p>Yes </p> </entry>
</row>
<row>
<entry><p>Context Id </p> </entry>
<entry><p>Yes </p> </entry>
<entry><p>Yes </p> </entry>
<entry><p>Yes </p> </entry>
</row>
<row>
<entry><p>PC value </p> </entry>
<entry><p>Yes </p> </entry>
<entry><p>Yes </p> </entry>
<entry><p>Yes </p> </entry>
</row>
<row>
<entry><p>the 32-bit integer value passed as aUserData </p> </entry>
<entry><p>NO </p> </entry>
<entry><p>Yes </p> </entry>
<entry><p>Yes </p> </entry>
</row>
<row>
<entry><p>the 32-bit integer value passed as aUserData2 </p> </entry>
<entry><p>NO </p> </entry>
<entry><p>NO </p> </entry>
<entry><p>Yes </p> </entry>
</row>
<row>
<entry><p>Tick Count as returned from a call to <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-CAE58268-9553-37B3-9669-EACD32A1A662"><apiname>NKern::TickCount()</apiname></xref>  </p> </entry>
<entry><p>Yes </p> </entry>
<entry><p>Yes </p> </entry>
<entry><p>Yes </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
<section id="GUID-70DA77F8-2B90-41B3-9373-7AE902FDE0EA"><title>How to use the macros</title> <p>To use the macros: </p> <ul>
<li id="GUID-4A92EAE7-B042-524B-B007-7828ECC99EC5"><p>Include the header file <filepath>kernperfloger.h</filepath> in
your source code. </p> </li>
<li id="GUID-A7A4BEED-F4D5-5D08-A4CB-0C088336FE37"><p>Link to <codeph>btrace.lib</codeph> in
your project </p> </li>
<li id="GUID-BF42F248-7D2B-5BE3-87CD-5CEEDBF0B3A5"><p>Call the <codeph>PERF_LOG***</codeph> macros
at appropriate points in your code. </p> <p>For examples, see the test code
for the macros in <filepath>...\e32test\group\d_perflogger_test_ldd.mmp</filepath> and <filepath>...\e32test\group\t_perflogger.mmp</filepath>  </p> </li>
<li id="GUID-B3C6CA8D-7257-59B8-8F96-D7F848F76223"><p>Rebuild your project </p> </li>
</ul> </section>
</conbody></concept>