How to Use ULogger with Comms

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.

Note: For more information, see Symbian^3 Tools Guide > Debugging .

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

1. 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.

2. 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
           

3. Start ULogger - The following command starts ULogger with the filter:

            ulogger -rv
           

4. Run the code under observation - In the first Eshell session, run the code to be tested or debugged.

5. Stop ULogger - To stop ULogger and generate the logs, use the command:

            ulogger -qv
           

6. 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.

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