7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept id="GUID-8105D1FC-DFFE-59F0-A664-3DA44F002F47" xml:lang="en"><title>Enabling |
12 <concept id="GUID-8105D1FC-DFFE-59F0-A664-3DA44F002F47" xml:lang="en"><title>Enabling File Server Tracing</title><shortdesc>This document describes how to enable trace points in the |
13 File Server Tracing</title><shortdesc>This document describes how to enable trace points in the file |
13 file server client API (EFSRV.DLL), the file system API (*.FSY) , |
14 server client API (EFSRV.DLL), the file system API (*.FSY) , and/or the proxy |
14 and/or the proxy drive API. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
15 drive API. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
15 <section id="GUID-E4208794-E751-4626-A457-FB81B330AC9E"><title>Introduction</title> <p>Enabling a trace point results in trace data being output to |
16 <section id="GUID-E4208794-E751-4626-A457-FB81B330AC9E"><title>Introduction</title> <p>Enabling a trace point |
16 the trace buffer. </p> <p>Tracing can be enabled or disabled (i.e. |
17 results in trace data being output to the trace buffer. </p> <p>Tracing can |
17 compiled in or out) at build time. By default file server tracing |
18 be enabled or disabled (i.e. compiled in or out) at build time. By default |
18 is enabled in debug builds of EFSRV.DLL and EFILE.EXE and disabled |
19 file server tracing is enabled in debug builds of EFSRV.DLL and EFILE.EXE |
19 in release builds. To enable tracing in release builds, there are |
20 and disabled in release builds. To enable tracing in release builds, there |
20 two options: </p> <ul> |
21 are two options: </p> <ul> |
21 <li id="GUID-CE4CBA1C-D699-568D-B97D-98CD01E7ADAC"><p>replace the |
22 <li id="GUID-CE4CBA1C-D699-568D-B97D-98CD01E7ADAC"><p>replace the release |
22 release builds of <filepath>EFSRV.DLL</filepath> /<filepath>EFILE.EXE</filepath> with their debug equivalents. </p> </li> |
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> |
23 <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 |
24 </ul> <p>Tracing can also be enabled or disabled at run time or at |
27 startup. For more details, see <xref href="GUID-D5984540-A411-52ED-B435-94C67F34ADD5.dita">How |
25 device startup. For more information, see <b>Symbian^3 Tools Guide |
28 to enable tracing</xref>. </p> <p>The level of tracing required may be configured |
26 > Debugging</b>. </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 |
27 by selecting one or more of the primary filters and one or more of |
30 filters from the list below: </p> <codeblock id="GUID-DDA48DE7-651D-54D4-A3EA-81C053D5F4BC" xml:space="preserve">//Primary filters |
28 the secondary 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 |
29 EPanic = 192 // to trace panics |
32 EError = 193 // to trace errors |
30 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 |
31 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) |
32 EF32TraceUidEfsrv = 0x100039e4 // (268450276 in decimal) |
35 EF32TraceUidFileSys = 0x10286575 // (271082869 in decimal) |
33 EF32TraceUidFileSys = 0x10286575 // (271082869 in decimal) |
36 EF32TraceUidProxyDrive = 0x10286576 // (271082870 in decimal)</codeblock><p> For |
34 EF32TraceUidProxyDrive = 0x10286576 // (271082870 in decimal)</codeblock><p> For more information on capturing the trace data, see <b>Symbian^3 |
37 more details on capturing the trace data see <xref href="GUID-71884BEF-0A49-5F56-BE26-EFFD77FA846A.dita">how |
35 Tools Guide > Debugging</b>. </p> </section> |
38 to output traces</xref>. </p> </section> |
36 <section id="GUID-AF241F65-5BCA-4BDA-9852-EF6033574A5E"><title>APIs </title> <p>The following table lists the classes to which the trace points |
39 <section id="GUID-AF241F65-5BCA-4BDA-9852-EF6033574A5E"><title>APIs </title> <p>The following table lists the classes to |
37 have been added. It has been divided into three broad categories as |
40 which the trace points have been added. It has been divided into three broad |
38 shown below. </p> <ul> |
41 categories as shown below. </p> <ul> |
|
42 <li id="GUID-930F772C-DC22-5D44-92D5-1EED6CDC02A9"><p> <b>File system</b> </p> <ul> |
39 <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> |
40 <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> |
41 <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> |
42 <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> |
43 <li id="GUID-08DCCC4C-2A4B-560C-96C2-55C949086F4B"><p> <xref href="GUID-B19ADEA9-5018-3773-92BC-C16306D15043.dita"><apiname>CDirCB</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> |
54 <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> |
55 <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> |
56 <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> |
57 <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> |
58 </ul> </li> |
62 </ul> <p>Trace points have been added to the public exported functions of |
59 </ul> <p>Trace points have been added to the public exported functions |
63 the classes listed above. As an example, the code fragment below illustrates |
60 of the classes listed above. As an example, the code fragment below |
64 how the tracepoints have been added and what type of information is output |
61 illustrates how the tracepoints have been added and what type of information |
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"> |
62 is output 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) |
63 EFSRV_EXPORT_C TInt RFile::Open(RFs& aFs,const TDesC& aName,TUint aMode) |
67 { |
64 { |
68 TRACEMULT3(UTF::EBorder, UTraceModuleEfsrv::EFileOpen, MODULEUID, aFs.Handle(), aMode, aName); |
65 TRACEMULT3(UTF::EBorder, UTraceModuleEfsrv::EFileOpen, MODULEUID, aFs.Handle(), aMode, aName); |
69 |
66 |
70 aMode &= ~EFileBigFile; |
67 aMode &= ~EFileBigFile; |
72 |
69 |
73 TRACERET2(UTF::EBorder, UTraceModuleEfsrv::EFileOpenReturn, MODULEUID, r, SubSessionHandle()); |
70 TRACERET2(UTF::EBorder, UTraceModuleEfsrv::EFileOpenReturn, MODULEUID, r, SubSessionHandle()); |
74 |
71 |
75 return r; |
72 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> |
73 }</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 |
74 <section id="GUID-A46311CE-B4C4-4BE9-A698-5DC1C18D6C60"><title>Interpretation |
78 currently provide a tool for decoding file server trace data (though hopefully |
75 of the trace data</title> <p>Symbian does not currently provide a |
79 this will change in the near future). The data can, however, be interpreted |
76 tool for decoding file server trace data (though hopefully this will |
80 by examining the following two publicly exported header files which provides |
77 change in the near future). The data can, however, be interpreted |
81 detail of what fields are output by each tracepoint. </p> <ul> |
78 by examining the following two publicly exported header files which |
|
79 provides 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> |
80 <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> |
81 <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"> |
82 </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" */ |
83 /** @SYMTraceFormatString "RFile::Replace() sess %x mode %x FileName %*S" */ |
86 EFileReplace</codeblock> <p>In the above example the trace record will contain |
84 EFileReplace</codeblock> <p>In the above example the trace record |
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> |
85 will contain the session <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref> handle, the file open |
|
86 mode and the filename. </p> </section> |
88 </conbody><related-links> |
87 </conbody><related-links> |
89 <link href="GUID-A3E77067-7982-5803-A274-0C8F2562B483.dita"><linktext>Unified Trace |
88 <link href="GUID-7B477BA5-CC5B-56A2-82BC-E1BC0049FECB.dita"><linktext>Kernel |
90 solution</linktext></link> |
89 Trace Tool Overview</linktext></link> |
91 <link href="GUID-7B477BA5-CC5B-56A2-82BC-E1BC0049FECB.dita"><linktext>Kernel Trace |
|
92 Tool Overview</linktext></link> |
|
93 </related-links></concept> |
90 </related-links></concept> |