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