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-9D26E38F-5C7B-5330-A54B-8F97D0F204D0" xml:lang="en"><title>Performance

    13 Logging</title><shortdesc>Symbian platform provides macros that you can use in device driver

    14 and kernel extension programs to write a trace log. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p>You can use the trace log to test the performance of the programs. </p>

    16 <section id="GUID-C332215D-B9E8-415B-8246-27D69F6A6E74"><title>Perfomance macros</title> <p>There are three macros that you

    17 can insert into your code. They only differ with respect to the optional data

    18 that you can add to the trace record. All are defined in <filepath>kernperfloger.h</filepath>  </p> <ul>

    19 <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>

    20 <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>

    21 <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:

    22 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>

    23 </ul> <p>You must specify an the 8-bit integer subcategory value in the <codeph>aSubCategory</codeph> argument.

    24 You can also supply one or two (or zero) 32-bit values; you are free to decide

    25 on the meaning of such values. </p> <p>The macros wrap around the standard <codeph>BTrace***</codeph> macros.

    26 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

    27 generation and capture of trace information is implemented as a kernel extension.

    28 This means that it is loaded and activated at an early stage in the startup

    29 process of the device. </p> </section>

    30 <section id="GUID-AD31830B-ED00-436F-9B36-EB3B3B0BFE4F"><title>Performance macro output format</title> <p>The following table

    31 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>,

    32 and <xref href="GUID-78D928F5-0ADA-31BE-A71D-0542A9B6E3D6.dita"><apiname>PERF_LOG2</apiname></xref>: </p> <table id="GUID-B409B220-479A-5999-A746-33787F764B6C">

    33 <tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>

    34 <tbody>

    35 <row>

    36 <entry><p> <b>Field</b>  </p> </entry>

    37 <entry><p> <b>PERF_LOG0</b>  </p> </entry>

    38 <entry><p> <b>PERF_LOG1</b>  </p> </entry>

    39 <entry><p> <b>PERF_LOG2</b>  </p> </entry>

    40 </row>

    41 <row>

    42 <entry><p>Fast Counter Timestamp </p> </entry>

    43 <entry><p>Yes </p> </entry>

    44 <entry><p>Yes </p> </entry>

    45 <entry><p>Yes </p> </entry>

    46 </row>

    47 <row>

    48 <entry><p>Context Id </p> </entry>

    49 <entry><p>Yes </p> </entry>

    50 <entry><p>Yes </p> </entry>

    51 <entry><p>Yes </p> </entry>

    52 </row>

    53 <row>

    54 <entry><p>PC value </p> </entry>

    55 <entry><p>Yes </p> </entry>

    56 <entry><p>Yes </p> </entry>

    57 <entry><p>Yes </p> </entry>

    58 </row>

    59 <row>

    60 <entry><p>the 32-bit integer value passed as aUserData </p> </entry>

    61 <entry><p>NO </p> </entry>

    62 <entry><p>Yes </p> </entry>

    63 <entry><p>Yes </p> </entry>

    64 </row>

    65 <row>

    66 <entry><p>the 32-bit integer value passed as aUserData2 </p> </entry>

    67 <entry><p>NO </p> </entry>

    68 <entry><p>NO </p> </entry>

    69 <entry><p>Yes </p> </entry>

    70 </row>

    71 <row>

    72 <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>

    73 <entry><p>Yes </p> </entry>

    74 <entry><p>Yes </p> </entry>

    75 <entry><p>Yes </p> </entry>

    76 </row>

    77 </tbody>

    78 </tgroup>

    79 </table> </section>

    80 <section id="GUID-70DA77F8-2B90-41B3-9373-7AE902FDE0EA"><title>How to use the macros</title> <p>To use the macros: </p> <ul>

    81 <li id="GUID-4A92EAE7-B042-524B-B007-7828ECC99EC5"><p>Include the header file <filepath>kernperfloger.h</filepath> in

    82 your source code. </p> </li>

    83 <li id="GUID-A7A4BEED-F4D5-5D08-A4CB-0C088336FE37"><p>Link to <codeph>btrace.lib</codeph> in

    84 your project </p> </li>

    85 <li id="GUID-BF42F248-7D2B-5BE3-87CD-5CEEDBF0B3A5"><p>Call the <codeph>PERF_LOG***</codeph> macros

    86 at appropriate points in your code. </p> <p>For examples, see the test code

    87 for the macros in <filepath>...\e32test\group\d_perflogger_test_ldd.mmp</filepath> and <filepath>...\e32test\group\t_perflogger.mmp</filepath>  </p> </li>

    88 <li id="GUID-B3C6CA8D-7257-59B8-8F96-D7F848F76223"><p>Rebuild your project </p> </li>

    89 </ul> </section>

    90 </conbody></concept>