--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-ABE77283-EED8-5A33-B574-3B771EF11086.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,155 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"Eclipse Public License v1.0" which accompanies this distribution,
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<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>
+<p>This tutorial summarises one approach for enabling, retrieving and post-processing
+the <xref href="GUID-B25AB5A9-52A6-50C2-8656-F8ADEE260FC9.dita">ULogger</xref> logs
+for Comms. ULogger is part of the Unified Trace framework which replaces other
+logging mechanisms for Symbian OS including Flogger and CDU. </p>
+<p>The Unified Trace framework has greater flexibility and speed compared
+to Flogger and CDU. </p>
+<section><title>Introduction</title> <p>The Comms logging which has been migrated
+to ULogger is as follows: </p> <ul>
+<li id="GUID-677DDC92-E655-50AD-85A3-7B6817F9E12A"><p>Comms Framework Node
+messages - creation and destruction of Nodes and messages between Nodes. </p> </li>
+<li id="GUID-E496D531-2CF2-5042-8820-BC8CE75CE4C6"><p>Mesh Machine messages </p> </li>
+<li id="GUID-E4892E5F-845B-5672-AB90-944A8B7DAEBE"><p>data to support the
+SVG generation </p> </li>
+</ul> <p>This logging replaces some of what was logged through the "<codeph>LOG
+CFNode *</codeph> ", "<codeph>LOG Mesh *</codeph> " and "<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 CDU. </p> <p>This usage description
+assumes that the development tools already include ULogger support. </p> </section>
+<section><title>Procedure - Using ULogger</title> <p><b>Requirements</b></p> <p>
+ For this tutorial, 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>
+<li><p> <filepath>nodemessages.dll</filepath>
+ </p> </li>
+<li><p> <filepath>meshmachine.dll</filepath>
+ </p> </li>
+<li><p> <filepath>commsfw.dll</filepath> </p> </li>
+<li><p> <filepath>serverden.dll</filepath> </p> </li>
+<li><p> <filepath>esocksvr.dll</filepath> </p> </li>
+</ul><p> To enable logging for a binary either use the UDEB version of the
+ binary or rebuild the binary with the <codeph>SYMBIAN_TRACE_ENABLED</codeph> macro
+defined. </p></section>
+<section><title>Steps</title> <ol>
+<li id="GUID-E3B09A4E-C87A-45F9-8DE6-653BA1A2E426"><p> <b>Start
+Eshell</b> - ULogger only supports asynchronous logging, so
+from EShell start a second instance of EShell. </p> <codeblock xml:space="preserve">start eshell</codeblock> <p>
+ This allows ULogger to be stopped even if the code under
+ observation does not exit normally. </p> </li>
+<li id="GUID-8A912D95-8D99-4D2A-9A5E-C51132924DAC"><p> <b>Set
+the ULogger Filters</b> - To allow Comms logging enable the
+following filters: </p><table id="GUID-56D45DFD-FD08-4B16-AB72-E5DD51C888E1">
+<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
+<thead>
+<row>
+<entry>Level</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry> <p> 194 </p></entry>
+<entry> <p> Node Messages </p></entry>
+</row>
+<row>
+<entry> <p> 195 </p></entry>
+<entry> <p> Mesh Machine </p></entry>
+</row>
+<row>
+<entry> <p> 196 </p></entry>
+<entry> <p> SVG Logging - provides extra logging so
+that 194 and 195 can be displayed in an SVG file
+ </p></entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p> The following filter is also useful:
+ </p> <table id="GUID-F2BA543D-0396-4552-9546-EF332B6BD747">
+<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
+<thead>
+<row>
+<entry>Level</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry> <p> 3</p></entry>
+<entry> <p> Kernel Thread ID's - Thread and process
+creation </p></entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p> Set these filters with the following command:
+ </p> <codeblock xml:space="preserve">ulogger -efv 194 195 3 196
+ </codeblock> </li>
+<li id="GUID-72C31641-7F65-4AA8-83BB-752E7A6EE77E"><p> <b>Start
+ULogger</b> - The following command starts ULogger with the
+filter: </p> <codeblock xml:space="preserve">
+
+ulogger -rv</codeblock> </li>
+<li id="GUID-CEDCDC01-1E86-4A67-9822-D94370DAF5E8"><p> <b>Run
+the code under observation</b> - In the first Eshell session,
+run the code to be tested or debugged. </p> </li>
+<li id="GUID-8EA473A7-6609-48C2-8E66-BA56D0178669"><p> <b>Stop
+ULogger</b> - To stop ULogger and generate the logs, use the
+command: </p> <codeblock xml:space="preserve">ulogger -qv</codeblock> </li>
+<li id="GUID-AC7549F8-4010-45D6-8C76-9322C16C86A1"><p> <b>Process
+the binary logs into text</b> - The log file created by ULogger
+is in a binary format and is located in the <filepath>c:\logs</filepath> folder
+on the device. </p> <p> To use the log file,
+the file must be converted to a text format.
+ </p> <p> The Comms software has a decoder to interpret the
+ULogger output for Comms. This decoder is an MS Windows-compatible
+application and is located in <filepath>…\os\commsfw\commsfwtools\</filepath>.
+ </p> <p> An example command to run the decoder
+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 the binary data
+in the log, and the decoder has definition files configured
+for the current scope of Comms logging. This example uses
+the ESock messages definition file, which is located in
+ <filepath>…\os\commsfw\commsfwtools\commstools\utracedecoder\data\esockmessages.definition.txt</filepath>.
+ </p> <p> The output in log.txt
+contains an interpretation of the original binary logs.
+ </p> </li>
+<li id="GUID-73E7C874-4487-492C-875C-642ECEBDF74F"><p> <b>Generating
+the SVG diagram</b> - The exchange of messages between Nodes
+can be rendered into a diagram. </p> <p> From <filepath>…\os\commsfw\commsfwtools\commstools\svg</filepath> run
+ <filepath>parseit.bat</filepath> specifying 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">
+<desc>Example SVG output from the Message Sequence Display Tool </desc>
+<image href="GUID-D7E5FECF-0B29-5908-A163-37036DF165E1_d0e65485_href.png" placement="inline"/>
+</fig> <p> Key to the SVG diagram: </p> <ol>
+<li id="GUID-64C07144-E5BD-465E-915F-1A867AD62FAB"><p>
+ Vertical black lines are tagged with names to represent node
+ lifetimes. For example: <codeph>IPCpr</codeph>
+ </p> </li>
+<li id="GUID-4BEE656D-9DEB-402B-B3A9-3A5C822B5E99"><p>
+ Vertical lines forking from the node lifetime lines are
+ MeshMachine activity lifetimes. </p> </li>
+<li id="GUID-BA5C28EF-856F-45CD-B6B8-AD1C0D663CA1"><p>
+ Black horizontal lines are message deliveries. </p> </li>
+<li id="GUID-61D41E05-7269-4A95-843D-E536141E56E0"><p>
+ Green horizontal lines are message postings. </p> </li>
+</ol> <p> New message types can be added to the definition
+files. See the documentation with the utracedecoder component.
+ </p> </li>
+</ol></section>
+</conbody><related-links>
+<link href="GUID-A3E77067-7982-5803-A274-0C8F2562B483.dita"><linktext>Unified Trace
+Solution</linktext></link>
+<link href="GUID-9006B4EE-194E-50FA-A803-F9EAA13E14AA.dita"><linktext>How to Use
+the ULogger Configuration File</linktext></link>
+</related-links></concept>
\ No newline at end of file