How +to Use ULogger with Comms

This tutorial summarises 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 OS including Flogger and CDU.

The Unified Trace framework has greater flexibility and speed compared +to Flogger and CDU.

Introduction

The Comms logging which has been migrated +to ULogger is as follows:

Comms Framework Node +messages - creation and destruction of Nodes and messages between Nodes.
Mesh Machine messages
data to support the +SVG generation

This logging replaces some of what was logged through the "LOG +CFNode * ", "LOG Mesh * " and "LOG ESock +* " tags. In the case of the ESock tag, the logging +which is written to ULogger is also written to CDU.

This usage description +assumes that the development tools already include ULogger support.

Procedure - Using ULogger

Requirements

+ For this tutorial, the code under observation must be run from EShell.

+ The following binaries must include logging:

nodemessages.dll +
meshmachine.dll +
commsfw.dll
serverden.dll
esocksvr.dll

To enable logging for a binary either use the UDEB version of the + binary or rebuild the binary with the SYMBIAN_TRACE_ENABLED macro +defined.

Steps

Start +Eshell - ULogger only supports asynchronous logging, so +from EShell start a second instance of EShell.
start eshell
+ This allows ULogger to be stopped even if the code under + observation does not exit normally.
Set +the ULogger Filters - To allow Comms logging enable the +following filters:
+ + + +Level +Description + + + + +
194
+
Node Messages
+ + +
195
+
Mesh Machine
+ + +
196
+
SVG Logging - provides extra logging so +that 194 and 195 can be displayed in an SVG file +
+ + + +

The following filter is also useful: +
+ + + +Level +Description + + + + +
3
+
Kernel Thread ID's - Thread and process +creation
+ + + +

Set these filters with the following command: +
ulogger -efv 194 195 3 196 +
Start +ULogger - The following command starts ULogger with the +filter:
+ +ulogger -rv
Run +the code under observation - In the first Eshell session, +run the code to be tested or debugged.
Stop +ULogger - To stop ULogger and generate the logs, use the +command:
ulogger -qv
Process +the binary logs into text - The log file created by ULogger +is in a binary format and is located in the c:\logs folder +on the device.

To use the log file, +the file must be converted to a text format. +

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 …\os\commsfw\commsfwtools\. +

An example command to run the decoder +is:
utracedecoder - -message-def esockmessages.definition.txt ulogger.log > log.txt
+ 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 + …\os\commsfw\commsfwtools\commstools\utracedecoder\data\esockmessages.definition.txt. +

The output in log.txt +contains an interpretation of the original binary logs. +
Generating +the SVG diagram - The exchange of messages between Nodes +can be rendered into a diagram.

From …\os\commsfw\commsfwtools\commstools\svg run + parseit.bat specifying the path to the +generated log.txt file:
parseit.bat /log M:\path_to_log_file\log.txt +Example SVG output from the Message Sequence Display Tool + +
Key to the SVG diagram:
1. + Vertical black lines are tagged with names to represent node + lifetimes. For example: IPCpr +
2. + Vertical lines forking from the node lifetime lines are + MeshMachine activity lifetimes.
3. + Black horizontal lines are message deliveries.
4. + Green horizontal lines are message postings.
New message types can be added to the definition +files. See the documentation with the utracedecoder component. +