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