Architecture of the Unified Trace Solution

The full Unified Trace solution consists of the following components:

• UTrace OS component: Includes UTrace API and ULogger engine.

• UTrace non-OS component: Includes host-side analysis tools, a command line interface, USB transport, and the host-side configuration.

The following diagram illustrates the high-level architecture of the Unified Trace solution.

	UTrace OS component
	UTrace non-OS component
Carbide	Provided by Nokia
TPTP	Provided by Eclipse
Trace viewer	Uses the TPTP module to view traces in CBE format.
Trace config API	Java API-Windows service and host-side device driver to remote configure ULogger
CLI	Command Line Interface used to configure ULogger
SysStarter	Used to start logging at device boot.
BTrace	Filters traces coming from UTrace
Buffer	BTrace.dll-provides an API to access the BTrace buffer, this implements the BTrace handler.

The tracing process consists of three basic phases:

• Instrumentation

  • Inserting trace macros in the application or component code using the UTrace API. Each trace is identified by a primary filter, and optionally a secondary filter.

  • Compiling and transferring the application to the target.

• Tracing

  • Enabling the logging of the traces on the target using ULogger. The ULogger uses filters to decide which traces are to be logged and which are to be discarded.

  • Starting the application to enable tracing.

  • Stopping the application to log the traces.

• Analysis

  • Transferring the resulting log file to a PC.

  • The logs could then be processed, analysed and viewed on screen in a human-readable format. A Trace Environment Developer can provide their own analysis tool, or the Carbide or Eclipse-based TPTP Log Viewer is available in particular CustKits.

ULogger enables you to configure and capture trace data from a device. ULogger engine comprises of the following components:

• RULogger client API

• Plug-in framework

ULogger engine component provides a client RULogger API that allows clients to connect to and configure the ULogger server. The ULogger engine allows Trace Collectors to do the following tasks:

• Configuration of the BTrace component settings; such as, the filters, the buffer size, and the data notification size.

• To select and configure the output mechanism for the trace data stream.

Using the RULogger client API

A Trace Collector, using the RULogger client API to customise their client, needs to follow these guidelines

• There can be multiple clients attached to the ULogger server, but only the latest set of configurations or settings are applicable to the device.

• Configuration settings are not allowed on a per client basis.

• Individual clients are not notified about the configuration changes. So it is recommended to check the latest configuration status of the ULogger engine, before using or changing the existing values.

To use the RULogger client API, complete the following steps:

1. Include the uloggerclient.lib library in the MMP file.

2. Call the RULogger client API from the epoc32/include/uloggerclient.h file.

ULogger engine component provides the following two types of plug-in frameworks that can be implemented for communication (input and output) channels.

• Output framework: The output framework transfers the trace data stream to the active output plug-in. By default, the ULogger engine includes a set of standard output plug-ins to handle the data through save-to-file and output-over-serial. The following table lists the types of output plug-ins:

  Output plug-in name	Plug-in file	Description
  File output plug-in	ULoggerFilePlugin.dll	Stores trace data stream to a file (on device). This is an efficient plug-in to obtain the trace information. The Trace Collector should be aware that if they chose to write the trace data directly to a file on the MMC card, the performance of tracing is depend on the physical properties of the card. So it is recommended to copy the trace information to a file on the system drive, and then copy the file to MMC after tracing is stopped.
  Serial output plug-in	ULoggerSerialPlugin.dll	Sends trace data stream through a serial port to store data on a remote PC. This is a least efficient method for obtaining the trace data and has a significant dependency on the quality of the host-side serial port monitor. Trace Collector should remember to ensure that the host and device are connected through a serial cable and the host-side software used to capture the trace data is correctly enabled.

  Also, a Trace Environment Developer can write additional plug-ins that can be used by the ULogger engine. By default, the preceding output plug-ins are pre-installed and available for activation; that is, they can be loaded, run and configured at the runtime. However, a tools vendor or ROM creator can remove them. For more information on writing a new plug-in, see Writing a new plug-in.

• Input framework: The input framework is responsible for transporting the configuration settings and run commands between the host and the ULogger engine.

Considerations for using the ULogger engine:

Trace Collectors should take into account the following considerations before using the ULogger engine:

• In order for the ULogger server to run, the BTrace kernel service and the BTrace device driver need to be present on the device.

• By default, for Symbian Ltd. OS kit, BTrace is built into OS v9.3 and later version, and UTrace is built into OS v9.4 and later version.

• The ULogger engine components are optional, so their availability for Trace Collectors and Trace Environment Developers depends on the supplied OS kit.

• When creating a ROM to run the ULogger on hardware, the ROM creator should ensure that the components are built in the ROM, or installed on the device.

  Note:For Symbian reference platforms, the btrace.iby and the ulogger.iby files are provided for creating a ROM.