<?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 summarizes one approach for enabling, retrieving
and post-processing the ULogger logs for Comms. ULogger
is part of the Unified Trace framework which replaces other logging
mechanisms for Symbian platform including Flogger and CDU. </p>
<p>The Unified Trace framework has greater flexibility and speed compared
to Flogger and CDU. </p>
<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>
<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><p>Note: For more information,
see <b>Symbian^3 Tools Guide &gt; Debugging</b>.</p>  </section>
<section id="GUID-BB759C19-49DA-48EA-8550-11B897A2E768"><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 id="GUID-72A353DC-CFD8-482E-B2E4-9CCCCD1C9BBA"><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 &gt; 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_d0e109389_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></concept>