<?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>