12 <concept xml:lang="en" id="GUID-715D065D-4FF7-55D0-882E-3B37F36369C4"><title>Overview of Unified Trace Solution</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>The Unified Trace solution is a framework that includes the UTrace API, a trace configuration tool and various APIs to allow extending the solution further. </p> <p>UTrace API is used to specify traces in the source code to output trace data. It uses a trace configuration tool to send the traces events and trace data. </p> <p>The trace configuration tool enables you to configure and output traces from a device. </p> <section><title>Purpose</title> <p>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. </p> <p>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. </p> </section> <section><title>Intended audience</title> <p>This guide is intended to application developers and device creators, who wants to do any or all of the following tasks: </p> <ul><li id="GUID-9E01A221-22C5-5540-99A2-94424DA564B1"><p>Instrument components to enable tracing </p> </li> <li id="GUID-DBABC106-0F8B-55CD-8A9C-AFB024D53A17"><p>Configure the trace framework optimally for a specific environment </p> </li> <li id="GUID-6E5BD3F5-F927-5B8C-B925-C97390A5E80B"><p>Enable and output traces for post processing </p> </li> <li id="GUID-E0967E3E-4491-58C0-ACD8-D4E87483A2A5"><p>Write input and output plug-ins for a specific environment. </p> </li> </ul> </section> <section><title>Required background</title> <p>Unified Trace solution users should be familiar with the following: </p> <ul><li id="GUID-469FB9D3-8C28-5800-B5D4-8ADC84007A76"><p>Symbian platform </p> </li> <li id="GUID-35CFCA0A-A815-582F-BE59-2FAE6D03DD8A"><p>BTrace. </p> </li> <li id="GUID-B94F6D34-9D25-5103-B346-4805A7742B03"><p>ECom framework. For more information on ECom, see <i>Using ECom</i>. </p> </li> </ul> </section> <section id="GUID-A7E551D1-DED5-5BC7-A19F-523B65B2AE00"><title>Key concepts and terms</title> <p>This section briefly explains important concepts of the Unified Trace solution. </p> <dl><dlentry><dt>UTrace</dt> <dd><p>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. </p> </dd> </dlentry> <dlentry><dt>Trace configuration tool</dt> <dd><p>A trace configuration tool is required to configure and output traces from a device. </p> </dd> </dlentry> </dl> <p>The following definitions describe the distinctions between the different types of users of the Unified Trace Solution: </p> <dl><dlentry><dt>Instrumentor</dt> <dd><p>Symbian developers who wish to add instrumentation to their user or kernel side components are referred as an Instrumentor. </p> <p>The component could be a device-driver, a communications stack, any other Symbian platform component, a UIQ/S60/MOAP component or an application. </p> <p>An Instrumentor inserts trace points into a component for the following reasons: </p> <ul><li id="GUID-7DFF1E51-4185-5D2B-BBB0-85A50CFB641C"><p>debugging the component </p> </li> <li id="GUID-FAA1840A-8F3E-545B-9EDF-535BBFA6E333"><p>debugging some secondary component that interacts with the component </p> </li> <li id="GUID-B7428C70-5B1C-5583-8797-DB71E6725A68"><p>profiling and analysing the performance of the component </p> </li> <li id="GUID-57960BDD-14E7-5426-96E2-133907664E31"><p>recording high-level system characteristics to aid later diagnosis. </p> </li> </ul> <p>For more information on inserting and enabling traces, see <xref href="GUID-AFB1F350-C5D3-5495-AE20-1AA6888B6FB1.dita">How to insert trace points in a component</xref> and <xref href="GUID-D5984540-A411-52ED-B435-94C67F34ADD5.dita">How to enable tracing</xref>. </p> </dd> </dlentry> <dlentry><dt>Trace Collector</dt> <dd><p>Symbian developers, 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. </p> <p>Trace Collectors are a superset of Instrumentors. </p> </dd> </dlentry> <dlentry><dt>Trace Environment Developers</dt> <dd><p>Symbian developers who want to write their own output plug-in specific to their hardware environment. </p> </dd> </dlentry> </dl> <p>The following definitions describe some important key terms the user needs to be familiar with before using the Unified Trace solution: </p> <dl><dlentry><dt>Instrumenting</dt> <dd><p>Inserting traces into the code. </p> </dd> </dlentry> <dlentry><dt>Tracing</dt> <dd><p>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. </p> </dd> </dlentry> <dlentry><dt>BTrace</dt> <dd><p>Collecting traces from various system components. </p> </dd> </dlentry> <dlentry><dt>Filters</dt> <dd><p>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. </p> <p>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 configuration filter settings to match the filter identifiers in the relevant trace points (through the trace configuration tool). </p> <p> <b>Types of filters</b> </p> <p>Following are the two types of filters: </p> <ul><li id="GUID-7C2DB64F-6CE6-5761-AEBC-8F98D02758C1"><p> <b> Primary filter:</b> 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. </p> <p>The 256 primary filters are split into several ranges, each with their own owner and purpose. </p> <p>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 <filepath>epoc32/include/e32btrace.h</filepath> file and use any of the undefined filters within the ranges allocated to them in it. </p> <p>The undefined primary filter ranges are are intended to be defined by the Symbian developers 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. </p> </li> <li id="GUID-C61EA20D-200C-5A0D-9788-08A99A9CD80D"><p> <b>Secondary filter:</b> 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. </p> </li> </ul> <p> <b>Relationship between primary and secondary filters</b> </p> <p>There are six filtering combinations that a Trace Collector can implement for tracing the data, provided in the following table. </p> <table id="GUID-8C32713A-2352-579F-85B3-EA933CBD4A5F"><tgroup cols="6"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/><colspec colname="col4"/><colspec colname="col5"/><thead><row><entry>Scenario</entry> <entry>Component trace point instrumentation</entry> <entry>Primary filter (P)</entry> <entry>Secondary filtering functionality</entry> <entry>Secondary filter (S)</entry> <entry>Trace output result</entry> </row> </thead> <tbody><row><entry><p>1 </p> </entry> <entry><p>P</p> </entry> <entry><p>Disabled </p> </entry> <entry><p>Not applicable </p> </entry> <entry><p>Not applicable </p> </entry> <entry><p>No </p> </entry> </row> <row><entry><p>2</p> </entry> <entry><p>P</p> </entry> <entry><p>Enabled </p> </entry> <entry><p>Not applicable </p> </entry> <entry><p>Not applicable </p> </entry> <entry><p>Yes </p> </entry> </row> <row><entry><p>3</p> </entry> <entry><p>P and S </p> </entry> <entry><p>Disabled </p> </entry> <entry><p>Not applicable </p> </entry> <entry><p>Not applicable </p> </entry> <entry><p>No </p> </entry> </row> <row><entry><p>4</p> </entry> <entry><p>P and S </p> </entry> <entry><p>Enabled </p> </entry> <entry><p>Disabled </p> </entry> <entry><p>Not applicable </p> </entry> <entry><p>Yes </p> </entry> </row> <row><entry><p>5</p> </entry> <entry><p>P and S </p> </entry> <entry><p>Enabled </p> </entry> <entry><p>Enabled </p> </entry> <entry><p>Disabled </p> </entry> <entry><p>No </p> </entry> </row> <row><entry><p>6</p> </entry> <entry><p>P and S </p> </entry> <entry><p>Enabled </p> </entry> <entry><p>Enabled </p> </entry> <entry><p>Enabled </p> </entry> <entry><p>Yes </p> </entry> </row> </tbody> </tgroup> </table> </dd> </dlentry> <dlentry><dt>Trace record format</dt> <dd><p>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. </p> <p>Note the following important distinctions in UTrace: </p> <ul><li id="GUID-229B6039-CD59-5A73-9B0A-F5190D15B256"><p>The category field in BTrace is referred to as the primary filter in UTrace. </p> </li> <li id="GUID-1B52E89D-E2C4-5477-B7ED-7DC9149C1BFB"><p>The secondary category field in BTrace is referred to as the secondary filter in UTrace. </p> </li> <li id="GUID-E846C634-2D2B-5D37-9B11-373BAF4D7919"><p>The sub-category field in BTrace is referred to as schema in UTrace. </p> </li> </ul> <fig id="GUID-73DE2A6F-E989-516D-9687-7ECCD0E657FE"><title> |
|