Overview of Unified Trace Solution

The Unified Trace solution is a framework that includes the UTrace API, the ULogger engine and various APIs to allow extending the solution further.

UTrace API is used to specify traces in the source code to output trace data. It uses the ULogger engine to send the traces events and trace data.

ULogger enables you to configure and output traces from a device. It provides a client or server API (RULogger client API) that enables clients to connect and configure the ULogger server.

The Unified Trace solution provides a platform independent, generic, and unified trace framework for outputting trace data. Trace data can be used to debug difficult run-time behaviour defects at all stages of the device creation cycle.

The Unified Trace solution also provides a filtering mechanism to ensure system intrusion is minimised to a maximum extent. Additionally, a user can extend or modify the Unified Trace solution to suit specific requirements. For more information on extending the Unified Trace solution, see How to extend the Unified Trace solution.

This guide is intended to application developers and device creators, who wants to do any or all of the following tasks:

• Instrument components to enable tracing

• Configure the trace framework optimally for a specific environment

• Enable and output traces for post processing

• Write input and output plug-ins for a specific environment.

Unified Trace solution users should be familiar with the following:

• Symbian OS

• BTrace. For more information on BTrace, see Base How to BTrace.

• ECom framework. For more information on ECom, see Using ECom.

This section briefly explains important concepts of the Unified Trace solution.

UTrace

The UTrace API is used to output significant information about a component. It is based on BTrace and extends BTrace, a tracer that is present in the kernel that can handle fast tracing both on kernel and user side of the OS.

ULogger

ULogger provides the engine for the user to configure and output traces from a device. It provides a client or server API (RULogger client API) that enables clients to connect and configure the ULogger server.

ULogger additionally includes two standard output plug-ins, file and serial, to output the trace log data. The user can optionally write custom output plug-in mechanisms to be used by ULogger as well.

The following definitions describe the distinctions between the different types of users of the Unified Trace Solution:

Instrumentor

Developers who wish to add instrumentation to their user or kernel side components are referred as an Instrumentor. These include Symbian licensee or third party developers; such as, tools vendors.

The component could be a device-driver, a communications stack, any other Symbian OS component, a UIQ/S60/MOAP component or an application.

An Instrumentor inserts trace points into a component for the following reasons:

• debugging the component

• debugging some secondary component that interacts with the component

• profiling and analysing the performance of the component

• recording high-level system characteristics to aid later diagnosis.

For more information on inserting and enabling traces, see How to insert trace points in a component and How to enable tracing.

Trace Collector

Software developers for Symbian OS, system characteristic analysts, system integrators and testers, who wish to extract trace data from the system by transporting the raw binary output off the device for post process analysis are referred as Trace Collector.

Trace Collectors are a superset of Instrumentors. They can be licensee or tools vendors who may wish to supply their own client for configuring and controlling ULogger.

For more information on outputting traces, see How to output trace data.

Trace Environment Developers

Developers who wish to write their own output plug-in specific to their hardware environment.

For more information on writing or modifying the input and output plug-in components, see How to extend the Unified Trace solution.

The following definitions describe some important key terms the user needs to be familiar with before using the Unified Trace solution:

Instrumenting

Inserting traces into the code.

Tracing

Capturing the trace data in a Symbian device at run-time, transferring it to a PC and storing in a file using UTrace. Trace data can be used to debug difficult run-time behaviour defects at all stages of the device creation cycle.

BTrace

Collecting traces from various system components.

Configuration file

The file used by the Ulogger server to configure settings for output and input channels, filtering and the BTrace buffer.

Filters

Filters are used to identify and select the traces that have to be logged. They also enable grouping of traces to ease the implementation of host-side trace analysis tools; such as, third party or Symbian log processing viewers.

The Unified Trace solution provides a filtering mechanism to ensure system intrusion is minimised as much as possible. Trace points, which have been compiled into the source component by the Instrumentor, are switched off (disabled) on the device at run-time. The Trace Collector then needs to actively set (enable) which trace packets they want to output by changing the ULogger configuration filter settings to match the filter identifiers in the relevant trace points (through the ULogger Client API or a UI wrapper). However, the default behaviour is determined by licensees in the ULogger configuration file, so it is feasible to have traces enabled at run-time on released devices for problem diagnosis.

Types of filters

Following are the two types of filters:

• Primary filter: Primary filters enable a low intrusion filtering mechanism, which is essential when instrumenting critical sections of the kernel or other key services. There are 256 primary filters available.

  The 256 primary filters are split into several ranges, each with their own owner and purpose.

  A number of Symbian primary filters are defined over and above the pre-existing primary filters provided in the kernel for system characteristics. Instrumentors can find the current definition in the epoc32/include/e32btrace.h file and use any of the undefined filters within the ranges allocated to them in it.

  The primary filter with the licensee ranges are undefined by Symbian and are intended to be defined by the licensee according to their own requirements. The distinction between Base-Port and UI or Applications is intended as a strong recommendation. It allows fast (primary filtered only) UTrace categories to be used in device drivers and other Base-Port code, without clashing with more general trace frameworks implemented for application layer code. This also allows for situations where a licensee has their own hardware and base-port, but license the UI from other sources.

• Secondary filter: Secondary filters allow a finer level of instrumentation and can be optionally applied to traces. It is recommended that secondary filters match the UID3 of the binary emitting the trace. Trace Collector can enable or disable the secondary filtering functionality using the configuration file. If the secondary filtering functionality is disabled, traces will be generated according to the primary filter identifier; regardless of the secondary filters set in the configuration file or assigned to the trace points.

Relationship between primary and secondary filters

There are six filtering combinations that a Trace Collector can implement for tracing the data, provided in the following table.

Scenario	Component trace point instrumentation	Primary filter (P)	Secondary filtering functionality	Secondary filter (S)	Trace output result
1	P	Disabled	Not applicable	Not applicable	No
2	P	Enabled	Not applicable	Not applicable	Yes
3	P and S	Disabled	Not applicable	Not applicable	No
4	P and S	Enabled	Disabled	Not applicable	Yes
5	P and S	Enabled	Enabled	Disabled	No
6	P and S	Enabled	Enabled	Enabled	Yes

Trace record format

The trace record format consists of a header and a payload. The minimum trace record consists of four bytes. Note that the trace record and payload must always be four byte aligned. For detailed information on header format, such as, the flags field and ROM build time settings related to timestamp, see Base How to BTrace.

Note the following important distinctions in UTrace:

• The category field in BTrace is referred to as the primary filter in UTrace.

• The secondary category field in BTrace is referred to as the secondary filter in UTrace.

• The sub-category field in BTrace is referred to as schema in UTrace.

Trace record

Currently, the Unified Trace solution does not support security. Instrumentors must ensure that the trace points do not contain any sensitive information that can be used to undermine the platform security.

The trace data available for all Symbian OS versions will not be the same. This is because of increasing instrumentation within Symbian OS with every release.