|
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><title>Introduction</title> <p>Enabling a trace point results in |
|
17 trace data being output to the trace buffer. </p> <p>Tracing can be enabled |
|
18 or disabled (i.e. compiled in or out) at build time. By default file server |
|
19 tracing is enabled in debug builds of EFSRV.DLL and EFILE.EXE and disabled |
|
20 in release builds. To enable tracing in release builds, there are two options: </p> <ul> |
|
21 <li id="GUID-CE4CBA1C-D699-568D-B97D-98CD01E7ADAC"><p>replace the release |
|
22 builds of <filepath>EFSRV.DLL</filepath> /<filepath>EFILE.EXE</filepath> with |
|
23 their debug equivalents. </p> </li> |
|
24 <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> |
|
25 </ul> <p>Tracing can also be enabled or disabled at run time or at device |
|
26 startup. For more details, see <xref href="GUID-D5984540-A411-52ED-B435-94C67F34ADD5.dita">How |
|
27 to enable tracing</xref>. </p> <p>The level of tracing required may be configured |
|
28 by selecting one or more of the primary filters and one or more of the secondary |
|
29 filters from the list below: </p> <codeblock id="GUID-DDA48DE7-651D-54D4-A3EA-81C053D5F4BC" xml:space="preserve">//Primary filters |
|
30 EPanic = 192 // to trace panics |
|
31 EError = 193 // to trace errors |
|
32 EBorder = 195, // to trace API calls</codeblock> <codeblock id="GUID-3253FF5A-ABAC-5A2D-9CE9-D420B855FB88" xml:space="preserve">//Secondary filters |
|
33 EF32TraceUidEfsrv = 0x100039e4 // (268450276 in decimal) |
|
34 EF32TraceUidFileSys = 0x10286575 // (271082869 in decimal) |
|
35 EF32TraceUidProxyDrive = 0x10286576 // (271082870 in decimal)</codeblock><p>For |
|
36 more details on capturing the trace data see <xref href="GUID-71884BEF-0A49-5F56-BE26-EFFD77FA846A.dita">how to output traces</xref>. |
|
37 </p> </section> |
|
38 |
|
39 <section><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><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> |