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-8105D1FC-DFFE-59F0-A664-3DA44F002F47" xml:lang="en"><title>Enabling

    13 File Server Tracing</title><shortdesc>This document describes how to enable trace points in the file

    14 server client API (EFSRV.DLL), the file system API (*.FSY) , and/or the proxy

    15 drive API. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    16 <section id="GUID-E4208794-E751-4626-A457-FB81B330AC9E"><title>Introduction</title> <p>Enabling a trace point

    17 results in trace data being output to the trace buffer. </p> <p>Tracing can

    18 be enabled or disabled (i.e. compiled in or out) at build time. By default

    19 file server tracing is enabled in debug builds of EFSRV.DLL and EFILE.EXE

    20 and disabled in release builds. To enable tracing in release builds, there

    21 are two options: </p> <ul>

    22 <li id="GUID-CE4CBA1C-D699-568D-B97D-98CD01E7ADAC"><p>replace the release

    23 builds of <filepath>EFSRV.DLL</filepath> /<filepath>EFILE.EXE</filepath> with

    24 their debug equivalents. </p> </li>

    25 <li id="GUID-76F59D55-BE9A-54E2-9A77-068F292334B0"><p>rebuild <filepath>EFSRV.DLL</filepath> /<filepath>EFILE.EXE</filepath> using <filepath>efsrv_instrumented.mmp</filepath> /<filepath>efile_instrumented.mmp</filepath>. </p> </li>

    26 </ul> <p>Tracing can also be enabled or disabled at run time or at device

    27 startup. For more details, see <xref href="GUID-D5984540-A411-52ED-B435-94C67F34ADD5.dita">How

    28 to enable tracing</xref>. </p> <p>The level of tracing required may be configured

    29 by selecting one or more of the primary filters and one or more of the secondary

    30 filters from the list below: </p> <codeblock id="GUID-DDA48DE7-651D-54D4-A3EA-81C053D5F4BC" xml:space="preserve">//Primary filters

    31 EPanic = 192            // to trace panics

    32 EError = 193            // to trace errors

    33 EBorder = 195,            // to trace API calls</codeblock> <codeblock id="GUID-3253FF5A-ABAC-5A2D-9CE9-D420B855FB88" xml:space="preserve">//Secondary filters

    34 EF32TraceUidEfsrv         =     0x100039e4 //    (268450276 in decimal)

    35 EF32TraceUidFileSys        =    0x10286575 //    (271082869 in decimal)

    36 EF32TraceUidProxyDrive    =    0x10286576 //    (271082870 in decimal)</codeblock><p> For

    37 more details on capturing the trace data see <xref href="GUID-71884BEF-0A49-5F56-BE26-EFFD77FA846A.dita">how

    38 to output traces</xref>.  </p> </section>

    39 <section id="GUID-AF241F65-5BCA-4BDA-9852-EF6033574A5E"><title>APIs </title> <p>The following table lists the classes to

    40 which the trace points have been added. It has been divided into three broad

    41 categories as shown below. </p> <ul>

    42 <li id="GUID-930F772C-DC22-5D44-92D5-1EED6CDC02A9"><p> <b>File system</b>  </p> <ul>

    43 <li id="GUID-938ED57F-0365-56BA-BD78-854CAE8BC344"><p> <xref href="GUID-0012B043-9FC4-3953-928E-CB6107E0486A.dita"><apiname>CFileSystem</apiname></xref>  </p> </li>

    44 <li id="GUID-5A54ADD0-2F79-54A2-8725-EE738F51FC5F"><p> <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita"><apiname>CMountCB</apiname></xref>  </p> </li>

    45 <li id="GUID-87CD0966-EE3B-5517-B69D-024B308EB4B1"><p> <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita"><apiname>CFileCB</apiname></xref>  </p> </li>

    46 <li id="GUID-08DCCC4C-2A4B-560C-96C2-55C949086F4B"><p> <xref href="GUID-B19ADEA9-5018-3773-92BC-C16306D15043.dita"><apiname>CDirCB</apiname></xref>  </p> </li>

    47 <li id="GUID-901B069A-A234-5238-94C0-B88723DA0698"><p> <xref href="GUID-E0C22CEA-845F-37A2-85DE-0ACD7927FA41.dita"><apiname>CFormatCB</apiname></xref>  </p> </li>

    48 </ul> </li>

    49 <li id="GUID-54DAF9C2-385A-5C5D-B808-DD42BD96D2B2"><p> <b>Proxy drive</b>  </p> <ul>

    50 <li id="GUID-D082BF1C-A7F1-597D-BE7E-19FDAFE25368"><p> <xref href="GUID-F47F56E4-3754-365B-B529-53C1D2A29503.dita"><apiname>CLocalProxyDrive</apiname></xref>  </p> </li>

    51 <li id="GUID-7115117E-68B1-5CCB-BEAE-668CF45DE9AD"><p> <xref href="GUID-FAFF712B-2295-3907-B839-D77F052160DA.dita"><apiname>CBaseExtProxyDrive</apiname></xref>  </p> </li>

    52 </ul> </li>

    53 <li id="GUID-ABC75EC4-EBBE-5F85-AA09-A1E77B121FBC"><p> <b>File server</b>  </p> <ul>

    54 <li id="GUID-54E6118B-454D-50B6-8BA1-6C5A74E6A70C"><p> <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref>  </p> </li>

    55 <li id="GUID-E9839BE3-3F7B-54BE-A52A-ECEBC4CE7691"><p> <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref>  </p> </li>

    56 <li id="GUID-5D365808-C2C1-5CC3-9E69-1423C47CBCE5"><p> <xref href="GUID-12AE154F-7741-38C0-ADFE-9784FCF5E516.dita"><apiname>RDir</apiname></xref>  </p> </li>

    57 <li id="GUID-D4F74F2A-F919-5AB9-89EA-1C45420E4391"><p> <xref href="GUID-9D7E765B-6872-3EB9-9D5B-1503FA466EC1.dita"><apiname>RFormat</apiname></xref>  </p> </li>

    58 <li id="GUID-39021B3E-2F79-51A7-8158-4D08B94CCF4D"><p> <xref href="GUID-118CCC9E-C58B-3AA0-86A8-219914E7E7BC.dita"><apiname>RPlugin</apiname></xref>  </p> </li>

    59 <li id="GUID-264C14C5-69D3-5662-9BFD-15B7FCB22F00"><p> <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita"><apiname>CFileMan</apiname></xref>  </p> </li>

    60 <li id="GUID-817F4158-5F9F-5D21-9FA1-42D5EC6F774F"><p> <xref href="GUID-C657AF2D-1183-3CD2-ACAF-3B0B00FC91BB.dita"><apiname>CDirScan</apiname></xref>  </p> </li>

    61 </ul> </li>

    62 </ul> <p>Trace points have been added to the public exported functions of

    63 the classes listed above. As an example, the code fragment below illustrates

    64 how the tracepoints have been added and what type of information is output

    65 for the Open function of the <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref> class: </p> <codeblock id="GUID-44DCCB86-9835-5A03-A17C-A78F43A58FD6" xml:space="preserve">

    66 EFSRV_EXPORT_C TInt RFile::Open(RFs& aFs,const TDesC& aName,TUint aMode)

    67 {

    68 TRACEMULT3(UTF::EBorder, UTraceModuleEfsrv::EFileOpen, MODULEUID, aFs.Handle(), aMode, aName);

    69 

    70 aMode &= ~EFileBigFile;

    71 TInt r = CreateSubSession(aFs,EFsFileOpen,TIpcArgs(&aName,aMode));

    72 

    73 TRACERET2(UTF::EBorder, UTraceModuleEfsrv::EFileOpenReturn, MODULEUID, r, SubSessionHandle());

    74 

    75 return r;

    76 }</codeblock> <p>A sample trace output is as shown: </p> <codeblock id="GUID-A7782683-9A99-5B9B-AD52-81CC236CB7D1" xml:space="preserve">RFile::Open() sess 0x00008000 mode 0x00000100 FileName Z:\SYS\DATA\ESTARTFILESYSTEMS.TXT</codeblock> </section>

    77 <section id="GUID-A46311CE-B4C4-4BE9-A698-5DC1C18D6C60"><title>Interpretation of the trace data</title> <p>Symbian does not

    78 currently provide a tool for decoding file server trace data (though hopefully

    79 this will change in the near future). The data can, however, be interpreted

    80 by examining the following two publicly exported header files which provides

    81 detail of what fields are output by each tracepoint. </p> <ul>

    82 <li id="GUID-3032957A-5D64-57AD-98FD-DF82D6959C10"><p> <filepath>\epoc32\include\utraceefsrv.h </filepath>  </p> </li>

    83 <li id="GUID-8C8C91AD-757A-5A79-861B-2686178FB154"><p> <filepath>\epoc32\include\utraceefile.h</filepath>  </p> </li>

    84 </ul> <p>For example: </p> <codeblock id="GUID-2B0DD8BA-5AC5-5369-8410-4A21B987D926" xml:space="preserve">

    85 /** @SYMTraceFormatString "RFile::Replace() sess %x mode %x FileName %*S" */

    86 EFileReplace</codeblock> <p>In the above example the trace record will contain

    87 the session <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref> handle, the file open mode and the filename. </p> </section>

    88 </conbody><related-links>

    89 <link href="GUID-A3E77067-7982-5803-A274-0C8F2562B483.dita"><linktext>Unified Trace

    90 solution</linktext></link>

    91 <link href="GUID-7B477BA5-CC5B-56A2-82BC-E1BC0049FECB.dita"><linktext>Kernel Trace

    92 Tool Overview</linktext></link>

    93 </related-links></concept>