|
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-ABE77283-EED8-5A33-B574-3B771EF11086" xml:lang="en"><title>How |
|
13 to Use ULogger with Comms</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This tutorial summarises one approach for enabling, retrieving and post-processing |
|
15 the <xref href="GUID-B25AB5A9-52A6-50C2-8656-F8ADEE260FC9.dita">ULogger</xref> logs |
|
16 for Comms. ULogger is part of the Unified Trace framework which replaces other |
|
17 logging mechanisms for Symbian platform including Flogger and |
|
18 CDU. </p> |
|
19 <p>The Unified Trace framework has greater flexibility and speed compared |
|
20 to Flogger and CDU. </p> |
|
21 <section id="GUID-6FF10945-4E25-4F91-BDA4-CC363EEC2480"><title>Introduction</title> <p>The Comms logging which has been migrated |
|
22 to ULogger is as follows: </p> <ul> |
|
23 <li id="GUID-677DDC92-E655-50AD-85A3-7B6817F9E12A"><p>Comms Framework Node |
|
24 messages - creation and destruction of Nodes and messages between Nodes. </p> </li> |
|
25 <li id="GUID-E496D531-2CF2-5042-8820-BC8CE75CE4C6"><p>Mesh Machine messages </p> </li> |
|
26 <li id="GUID-E4892E5F-845B-5672-AB90-944A8B7DAEBE"><p>data to support the |
|
27 SVG generation </p> </li> |
|
28 </ul> <p>This logging replaces some of what was logged through the "<codeph>LOG |
|
29 CFNode *</codeph> ", "<codeph>LOG Mesh *</codeph> " and "<codeph>LOG ESock |
|
30 *</codeph> " tags. In the case of the <codeph>ESock</codeph> tag, the logging |
|
31 which is written to ULogger is also written to CDU. </p> <p>This usage description |
|
32 assumes that the development tools already include ULogger support. </p> </section> |
|
33 <section id="GUID-BB759C19-49DA-48EA-8550-11B897A2E768"><title>Procedure - Using ULogger</title> <p><b>Requirements</b></p> <p> |
|
34 For this tutorial, the code under observation must be run from <xref href="GUID-D90C86C6-B85D-5941-9919-3725A9FFD548.dita">EShell</xref>. </p> <p> |
|
35 The following binaries must include logging: </p> <ul> |
|
36 <li><p> <filepath>nodemessages.dll</filepath> |
|
37 </p> </li> |
|
38 <li><p> <filepath>meshmachine.dll</filepath> |
|
39 </p> </li> |
|
40 <li><p> <filepath>commsfw.dll</filepath> </p> </li> |
|
41 <li><p> <filepath>serverden.dll</filepath> </p> </li> |
|
42 <li><p> <filepath>esocksvr.dll</filepath> </p> </li> |
|
43 </ul><p> To enable logging for a binary either use the UDEB version of the |
|
44 binary or rebuild the binary with the <codeph>SYMBIAN_TRACE_ENABLED</codeph> macro |
|
45 defined. </p></section> |
|
46 <section id="GUID-72A353DC-CFD8-482E-B2E4-9CCCCD1C9BBA"><title>Steps</title> <ol> |
|
47 <li id="GUID-E3B09A4E-C87A-45F9-8DE6-653BA1A2E426"><p> <b>Start |
|
48 Eshell</b> - ULogger only supports asynchronous logging, so |
|
49 from EShell start a second instance of EShell. </p> <codeblock xml:space="preserve">start eshell</codeblock> <p> |
|
50 This allows ULogger to be stopped even if the code under |
|
51 observation does not exit normally. </p> </li> |
|
52 <li id="GUID-8A912D95-8D99-4D2A-9A5E-C51132924DAC"><p> <b>Set |
|
53 the ULogger Filters</b> - To allow Comms logging enable the |
|
54 following filters: </p><table id="GUID-56D45DFD-FD08-4B16-AB72-E5DD51C888E1"> |
|
55 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
56 <thead> |
|
57 <row> |
|
58 <entry>Level</entry> |
|
59 <entry>Description</entry> |
|
60 </row> |
|
61 </thead> |
|
62 <tbody> |
|
63 <row> |
|
64 <entry> <p> 194 </p></entry> |
|
65 <entry> <p> Node Messages </p></entry> |
|
66 </row> |
|
67 <row> |
|
68 <entry> <p> 195 </p></entry> |
|
69 <entry> <p> Mesh Machine </p></entry> |
|
70 </row> |
|
71 <row> |
|
72 <entry> <p> 196 </p></entry> |
|
73 <entry> <p> SVG Logging - provides extra logging so |
|
74 that 194 and 195 can be displayed in an SVG file |
|
75 </p></entry> |
|
76 </row> |
|
77 </tbody> |
|
78 </tgroup> |
|
79 </table> <p> The following filter is also useful: |
|
80 </p> <table id="GUID-F2BA543D-0396-4552-9546-EF332B6BD747"> |
|
81 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
82 <thead> |
|
83 <row> |
|
84 <entry>Level</entry> |
|
85 <entry>Description</entry> |
|
86 </row> |
|
87 </thead> |
|
88 <tbody> |
|
89 <row> |
|
90 <entry> <p> 3</p></entry> |
|
91 <entry> <p> Kernel Thread ID's - Thread and process |
|
92 creation </p></entry> |
|
93 </row> |
|
94 </tbody> |
|
95 </tgroup> |
|
96 </table> <p> Set these filters with the following command: |
|
97 </p> <codeblock xml:space="preserve">ulogger -efv 194 195 3 196 |
|
98 </codeblock> </li> |
|
99 <li id="GUID-72C31641-7F65-4AA8-83BB-752E7A6EE77E"><p> <b>Start |
|
100 ULogger</b> - The following command starts ULogger with the |
|
101 filter: </p> <codeblock xml:space="preserve"> |
|
102 |
|
103 ulogger -rv</codeblock> </li> |
|
104 <li id="GUID-CEDCDC01-1E86-4A67-9822-D94370DAF5E8"><p> <b>Run |
|
105 the code under observation</b> - In the first Eshell session, |
|
106 run the code to be tested or debugged. </p> </li> |
|
107 <li id="GUID-8EA473A7-6609-48C2-8E66-BA56D0178669"><p> <b>Stop |
|
108 ULogger</b> - To stop ULogger and generate the logs, use the |
|
109 command: </p> <codeblock xml:space="preserve">ulogger -qv</codeblock> </li> |
|
110 <li id="GUID-AC7549F8-4010-45D6-8C76-9322C16C86A1"><p> <b>Process |
|
111 the binary logs into text</b> - The log file created by ULogger |
|
112 is in a binary format and is located in the <filepath>c:\logs</filepath> folder |
|
113 on the device. </p> <p> To use the log file, |
|
114 the file must be converted to a text format. |
|
115 </p> <p> The Comms software has a decoder to interpret the |
|
116 ULogger output for Comms. This decoder is an MS Windows-compatible |
|
117 application and is located in <filepath>…\os\commsfw\commsfwtools\</filepath>. |
|
118 </p> <p> An example command to run the decoder |
|
119 is: </p> <codeblock xml:space="preserve">utracedecoder - -message-def esockmessages.definition.txt ulogger.log > log.txt</codeblock> <p> |
|
120 The decoder uses a definition file to decipher the binary data |
|
121 in the log, and the decoder has definition files configured |
|
122 for the current scope of Comms logging. This example uses |
|
123 the ESock messages definition file, which is located in |
|
124 <filepath>…\os\commsfw\commsfwtools\commstools\utracedecoder\data\esockmessages.definition.txt</filepath>. |
|
125 </p> <p> The output in log.txt |
|
126 contains an interpretation of the original binary logs. |
|
127 </p> </li> |
|
128 <li id="GUID-73E7C874-4487-492C-875C-642ECEBDF74F"><p> <b>Generating |
|
129 the SVG diagram</b> - The exchange of messages between Nodes |
|
130 can be rendered into a diagram. </p> <p> From <filepath>…\os\commsfw\commsfwtools\commstools\svg</filepath> run |
|
131 <filepath>parseit.bat</filepath> specifying the path to the |
|
132 generated log.txt file: </p> <codeblock xml:space="preserve">parseit.bat /log M:\path_to_log_file\log.txt</codeblock><fig id="GUID-F6E85A8D-09B3-40A1-B3DC-5B968C3F1A4C"> |
|
133 <desc>Example SVG output from the Message Sequence Display Tool </desc> |
|
134 <image href="GUID-D7E5FECF-0B29-5908-A163-37036DF165E1_d0e85525_href.png" placement="inline"/> |
|
135 </fig> <p> Key to the SVG diagram: </p> <ol> |
|
136 <li id="GUID-64C07144-E5BD-465E-915F-1A867AD62FAB"><p> |
|
137 Vertical black lines are tagged with names to represent node |
|
138 lifetimes. For example: <codeph>IPCpr</codeph> |
|
139 </p> </li> |
|
140 <li id="GUID-4BEE656D-9DEB-402B-B3A9-3A5C822B5E99"><p> |
|
141 Vertical lines forking from the node lifetime lines are |
|
142 MeshMachine activity lifetimes. </p> </li> |
|
143 <li id="GUID-BA5C28EF-856F-45CD-B6B8-AD1C0D663CA1"><p> |
|
144 Black horizontal lines are message deliveries. </p> </li> |
|
145 <li id="GUID-61D41E05-7269-4A95-843D-E536141E56E0"><p> |
|
146 Green horizontal lines are message postings. </p> </li> |
|
147 </ol> <p> New message types can be added to the definition |
|
148 files. See the documentation with the utracedecoder component. |
|
149 </p> </li> |
|
150 </ol></section> |
|
151 </conbody><related-links> |
|
152 <link href="GUID-A3E77067-7982-5803-A274-0C8F2562B483.dita"><linktext>Unified Trace |
|
153 Solution</linktext></link> |
|
154 <link href="GUID-9006B4EE-194E-50FA-A803-F9EAA13E14AA.dita"><linktext>How to Use |
|
155 the ULogger Configuration File</linktext></link> |
|
156 </related-links></concept> |