1 /**

     2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 * Trace API

    16 *

    17 */

    18 

    19 

    20 

    21 /**

    22  @file

    23  @publishedPartner

    24  @prototype

    25 */

    26 

    27 

    28 #ifndef OPENSYSTEMTRACE_TYPES_H

    29 #define OPENSYSTEMTRACE_TYPES_H

    30 

    31 #ifdef __KERNEL_MODE__

    32 #include <kernel.h>

    33 #else //__KERNEL_MODE__

    34 #include <e32std.h>

    35 #endif //__KERNEL_MODE__

    36 

    37 

    38 /**

    39 @file

    40 @publishedPartner

    41 @prototype

    42 */

    43 

    44 

    45 /**

    46  * Every trace point must be statically assigned a group ID. This is

    47  * essentially a “label” that allows identification of the intended use of

    48  * the trace packets generated by the trace point. The Group ID will either 

    49  * reflect a system wide Tracing use cases, such as identifying why a panic 

    50  * occurred, or is assigned a meaning specific to a component, such as the 

    51  * heap trace output from the kernel. In essence the Group ID is a way of 

    52  * indicating that trace points / packets are related in some way. 

    53  * @see TGroupIdRange for more information.

    54  */

    55 typedef TUint8  TGroupId;

    56 

    57 /**

    58  * The maximum possible value for TGroupId

    59  */

    60 const static TGroupId KMaxGroupId = 255; // 2^8 - 1

    61 

    62 /**

    63  * @deprecated Use TGroupId instead

    64  * @see TGroupId

    65  */

    66 typedef TUint8  TClassification;

    67 

    68 /**

    69  * @deprecated Use KMaxGroupId instead

    70  * @see KMaxGroupId

    71  */

    72 const static TClassification KMaxClassification = KMaxGroupId;

    73 

    74 /**

    75  * Each trace point must be statically assigned a ComponentId to indicate the

    76  * module in which the trace point is defined. It should always be the UID3

    77  * of the binary containing the trace point associated with the component ID. 

    78 

    79  * The ComponentId and Group ID attributes of a trace point are independent.

    80  */

    81 typedef TUint32 TComponentId;

    82 

    83 /**

    84  * The maximum possible value for TComponentId

    85  */

    86 const static TComponentId KMaxComponentId = 0xFFFFFFFF; // 2^32 - 1, or 4294967295 - 1

    87 

    88 /**

    89  * The EXECUTABLE_DEFAULT_COMPONENTID can be used to define your own default

    90  * specific ComponentId. This is done by defining the macro to be your new

    91  * default value.

    92  */

    93 #ifdef EXECUTABLE_DEFAULT_COMPONENTID

    94 #define FW_DEFAULT_COMPONENTID EXECUTABLE_DEFAULT_COMPONENTID

    95 #else

    96 #define FW_DEFAULT_COMPONENTID TTraceContext::DefaultComponentId()

    97 #endif

    98 

    99 /**

   100  * Trace IDs have two functions in a trace packet:

   101  * 

   102  * 1. They identify the individual trace point that created the trace packet.

   103  * 2. They specify the format of the trace packet payload. 

   104  * 

   105  * This only works if the Trace ID value is unique for a given Group ID and 

   106  * Component ID, if present, and should be statically assigned during development 

   107  * when a trace point is created.  

   108  * 

   109  * The meaning of a TraceId is specific to the ComponentId and Group ID of the

   110  * associated trace point.

   111  */

   112 typedef TUint16 TTraceId;

   113 

   114 /**

   115  * The maximum possible value for TTraceId

   116  */

   117 const static TTraceId KMaxTraceId = 65535; // 2^16 - 1

   118 

   119 /**

   120  * Used in packets produced by the Print and Printf functions.

   121  *

   122  * Note that this format should not be used on the

   123  * device by clients of OST. This symbol is only marked

   124  * as published to partners to give host side tools access to

   125  * it.

   126  *

   127  * @deprecated No replacement is provided as this symbol is no 

   128  * longer needed as a result of the alignment of trace attributes 

   129  * in OSTv2.

   130  * @see TTraceId

   131  */

   132 const static TTraceId KFormatPrintf = 0;

   133 

   134 /**

   135  * Used in packets produced by the Print and Printf functions 

   136  * for unicode descriptors.

   137  *

   138  * Note that this format should not be used on the

   139  * device by clients of OST. This symbol is only marked

   140  * as published to partners to give host side tools access to

   141  * it.

   142  * 

   143  * @deprecated No replacement is provided as this symbol is no 

   144  * longer needed as a result of the alignment of trace attributes 

   145  * in OSTv2.

   146  * @see TTraceId

   147  */

   148 const static TTraceId KFormatPrintfUnicode = 1;

   149 

   150 /**

   151  * This value was used by UTFv2 clients to specify the start of 

   152  * the range of enums used to define their format ids. This is 

   153  * no longer necessary as in OSTv2 clients are allowed to use the

   154  * whole range without exception. 

   155  *

   156  * @deprecated No replacement is provided as this symbol is no 

   157  * longer needed as a result of the alignment of trace attributes 

   158  * in OSTv2.

   159  * @see TTraceId

   160  */

   161 const static TTraceId KInitialClientFormat = 512;

   162 

   163 /**

   164  * Include the thread identification into the trace packet at run-time.

   165  * The thread identification is used as an identifier to resolve

   166  * thread and process names in conjunction with

   167  * Group ID EThreadIdentification = 3.

   168  */

   169 enum THasThreadIdentification

   170     {

   171     /** Do add the thread identification to the trace packet */

   172     EAddThreadIdentification = ETrue,

   173     /** Don't add the thread identification */

   174     ENoThreadIdentification = EFalse

   175     };

   176 

   177 

   178 /**

   179  * The EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION can be used to

   180  * define the default setting for adding or not adding the thread

   181  * identification in a trace packet. This is done by defining

   182  * the macro to be your new default value.

   183  */

   184 #ifdef EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION

   185 #define FW_DEFAULT_HAS_THREAD_IDENTIFICATION EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION

   186 #else

   187 #define FW_DEFAULT_HAS_THREAD_IDENTIFICATION EAddThreadIdentification

   188 #endif

   189 

   190 

   191 /**

   192  * Add the program counter into the trace packet at run-time.

   193  * The program counter is used to indicate where the CPU is in the

   194  * instruction sequence. This can be used to locate the line of code

   195  * or routine the trace was sent from.

   196  */

   197 enum THasProgramCounter

   198     {

   199     /** Do add the program counter to the trace packet. */

   200     EAddProgramCounter = ETrue,

   201     /** Don't add the program counter */

   202     ENoProgramCounter = EFalse

   203     };

   204 

   205 

   206 /**

   207  * The EXECUTABLE_DEFAULT_HAS_PC can be used to

   208  * define the default setting for adding or not adding the

   209  * program counter in a trace packet. This is done by defining

   210  * the macro to be your new default value.

   211  */

   212 #ifdef EXECUTABLE_DEFAULT_HAS_PC

   213 #define FW_DEFAULT_HAS_PC EXECUTABLE_DEFAULT_HAS_PC

   214 #else

   215 #define FW_DEFAULT_HAS_PC ENoProgramCounter

   216 #endif

   217 

   218 /**

   219  * The division of the Group IDs into different ranges aims to manage the

   220  * contention for the namespace.

   221  *

   222  * It is recommended that all developers use the Reserved range as far as possible.

   223  *

   224  * @see TGroupId

   225  */

   226 enum TGroupIdRange

   227     {

   228     /**

   229      * The Group IDs in the Reserved range should be used by the majority of trace

   230      * points. This range of Group IDs are intended to identify which of the

   231      * most common trace use-cases a trace point is contributing to. They are unique

   232      * across the system.

   233      *

   234      * The Group IDs in this series are defined solely by the Symbian Foundation but are

   235      * intended for use by any software on a device.

   236      *

   237      * These Group IDs should only be enabled at run-time if the filtering on

   238      * ComponentIds functionality is also enabled. This is to avoid accidentally causing

   239      * trace live-locks from occurring when just the Group IDs is enabled. This could

   240      * happen because trace points in components involved in the current trace output

   241      * path might also be assigned these Group IDs. Filtering on ComponentIds means

   242      * that those trace points can be activated only when it’s known to be safe to do

   243      * so and not accidentally enabled with a Group IDs.

   244      *

   245      * @see TGroupIdReserved

   246      */

   247     EOstReservedRangeFirst = 0,

   248 

   249     /**

   250      * @see EOstReservedRangeFirst

   251      */

   252     EOstReservedRangeLast = 221,

   253 

   254     /**

   255      * The meaning of Group IDs in this range are defined on a per-component basis.

   256      * They are to be unique within a component.

   257      */

   258     EUserDefinedRangeFirst = 222,

   259 

   260     /**

   261      * @see EUserDefinedRangeFirst

   262      */

   263     EUserDefinedRangeLast = 253,

   264     

   265     /**

   266      * Only for use on the device by test code.

   267      *

   268      * Trace points with these Group IDs should not be released as part of a

   269      * production device.

   270      */

   271     ETestingRangeFirst = 154,

   272 

   273     /**

   274      * @see ETestingRangeFirst

   275      */

   276     ETestingRangeLast = KMaxGroupId

   277     };

   278 

   279 /**

   280  * The Group IDs in the Reserved range should be used by the majority of

   281  * trace points. This range of Group IDs are intended to identify which

   282  * of the most common trace use-cases a trace point is contributing to.

   283  *

   284  * @see TGroupId

   285  * @see TGroupIdRange

   286  * @see EOstReservedRangeFirst

   287  */

   288 enum TGroupIdReserved

   289     {

   290     /**

   291      * Used when a fatal error, such as a panic, has occurred or when providing information 

   292      * on the execution state immediately before the decision to panic.

   293      *

   294      * A trace point with this Group ID should be used when a fatal condition is detected 

   295      * which will result in the flow of execution being halted in the thread associated with 

   296      * the trace point.

   297      *

   298      * Can also provide information describing where a panic has been dealt with. 

   299      *

   300      * Trace points using this Group ID should be present in a release device. 

   301      */

   302     TRACE_FATAL = 149,

   303 

   304     /**

   305      * Used when an error has occurred which means that the current operation cannot continue 

   306      * but is not sufficiently serious to cause a fatal error. These trace packets should 

   307      * contain not just the error code but any relevant information about the execution state 

   308      * when the error occurred.

   309      *

   310      * To be used for all types of error including include situations where the errors are 

   311      * returned from a function or via a leave. 

   312      *

   313      * This Group ID also provides information describing where an error has been handled. 

   314      */

   315     TRACE_ERROR=150,

   316 

   317     /**

   318      * Used when something unexpected or unusual has occurred that does not stop the

   319      * current operation from happening but may result in unintended side effects or

   320      * actual errors later on.

   321      */

   322     TRACE_WARNING = 151,

   323 

   324     /**

   325      * Used to describe activity at the edges of a trace component. 

   326      *

   327      * Includes data about exported or published functions defined by a trace component as 

   328      * well as calls out of the component to get significant information. Exactly what 

   329      * is significant depends on the trace component in question. For instance, reading in a 

   330      * setting from an INI file would be significant but calling RArray::Count() would not be. 

   331      *

   332      * The information in this Group ID should be enough to allow someone unfamiliar with the 

   333      * trace component to get a high level understanding of what functionality it has executed.

   334      */

   335     TRACE_BORDER = 152,

   336     

   337     /**

   338     * @deprecated Use TRACE_BORDER instead

   339     */

   340     TRACE_API = TRACE_BORDER,

   341     

   342     /**

   343      * @deprecated Use TRACE_NORMAL or one of the other reserved Group IDs instead

   344      */

   345     TRACE_IMPORTANT = 153,

   346     

   347     /**

   348      * Used to described the normal activity within a trace component that might be of interest

   349      * to people who use the component.

   350      *

   351      * The information in this Group ID should be enough to allow someone unfamiliar with the 

   352      * trace component to start to understand why a component is behaving the way it is perhaps 

   353      * to help with diagnosing problems with the way the component is being used.

   354      */

   355     TRACE_NORMAL = 154,

   356 

   357     /**

   358      * Intended for tracing the state transitions of an application or service such as those

   359      * performed by a machine.

   360      *

   361      * Trace packets using this Group ID should contain the name of the

   362      * changed state variable and the new value.

   363      */

   364     TRACE_STATE  = 155,

   365 

   366     /**

   367      * Used to provide detailed information about the normal activity of a trace component

   368      * to help a developer, who is familiar with the component, to understand what it is doing.

   369      */

   370     TRACE_INTERNALS = 156,

   371 

   372     /**

   373     * @deprecated Use TRACE_INTERNALS instead

   374     */

   375     TRACE_DETAILED = TRACE_INTERNALS,

   376     

   377     /**

   378      * Used when there is a need to output large amounts of data through individual trace

   379      * points that would likely cause significant intrusion if included under one of the

   380      * other Group IDs.

   381      *

   382      * This Group ID is intended to be used in conjunction with the TRACE_INTERNALS

   383      * Group ID to provide more details when debugging a specific trace component.

   384      */

   385     TRACE_DUMP = 157,

   386 

   387     /**

   388     * @deprecated Use TRACE_DUMP instead

   389     */    

   390     TRACE_DEBUG = TRACE_DUMP,

   391     

   392     /**

   393      * Used to provide comprehensive information on what paths the execution takes within

   394      * functions.

   395      *

   396      * This Group ID is intended mainly to be used by tools that add temporary instrumentation 

   397      * points specifically to output this data.

   398      */

   399     TRACE_FLOW = 158,

   400 

   401     /**

   402      * Used to output data about the execution time, memory usage, disk usage, power

   403      * utilisation and any other performance characteristics of the associated trace 

   404      * component.

   405      *

   406      * This data may need to be processed before it can provide effective metrics. E.g.

   407      * the time between two timestamps might need to be computed.

   408      *

   409      * Intended only to be used to output a small amount of data to ensure that it 

   410      * creates the smallest possible intrusion since otherwise the act of tracing would 

   411      * devalue the information it is intended to provide.

   412      */

   413     TRACE_PERFORMANCE = 159,

   414 

   415     /**

   416      * May be used when adding temporary trace points during a debugging session to 

   417      * distinguish them from existing instrumentation. 

   418      */

   419     TRACE_ADHOC = 160,

   420     

   421     /**

   422      * This Group ID is reserved for future use to allow the Group ID range to be expanded 

   423      * to cover more than current 256 different values.

   424      *

   425      * If trace is output on this Group ID at some point in the future then this indicates 

   426      * that another mechanism (yet to be decided) will be used to indicate the actual 

   427      * Group ID for the trace.

   428      */

   429     TRACE_EXTENSION = 161,

   430 

   431     /**

   432 	 * Not intended to be used by code including this header.

   433 	 * 

   434      * Provided to allow the following compile time assert (should NOT be used):

   435      * EGroupIdReservedHighWaterMark <= EOstReservedRangeLast + 1

   436      *

   437      */

   438     EGroupIdReservedHighWaterMark

   439     } ;

   440 

   441 // Check high water mark for the reserved Group ID range

   442 __ASSERT_COMPILE(EGroupIdReservedHighWaterMark <= EOstReservedRangeLast + 1);

   443 

   444 /**

   445  * @see TGroupId

   446  * @see ETestingRangeFirst

   447  * @test

   448  */

   449 enum TGroupIdTesting

   450     {

   451     /**

   452      * This Group ID may be used for testing purposes and is not intended to be used in 

   453      * production code. 

   454      */

   455     TRACE_TESTING1 = ETestingRangeFirst,

   456 

   457     /**

   458      * The same as for TRACE_TESTING1

   459      */

   460     TRACE_TESTING2 = 155,

   461 

   462     /**

   463 	 * Not intended to be used by code including this header.

   464 	 * 

   465      * Provided to allow the following compile time assert (should NOT be used):

   466      * EGroupIdTestingHighWaterMark <= ETestingRangeLast + 1

   467      *

   468      */

   469     EGroupIdTestingHighWaterMark

   470     };

   471 

   472 // Check high water marks for the testing Group ID range

   473 __ASSERT_COMPILE(EGroupIdTestingHighWaterMark <= ETestingRangeLast + 1);

   474 

   475 /**

   476  * @deprecated Use enumerations from TGroupIdReserved instead

   477  * @see TGroupId

   478  * @see TGroupIdRange

   479  * @see EOstReservedRangeFirst

   480  */

   481 enum TClassificationAll

   482     {

   483     EPanic = TRACE_FATAL,

   484     EError = TRACE_ERROR,

   485     EWarning = TRACE_WARNING,

   486     EBorder = TRACE_BORDER,

   487     EState = TRACE_STATE,

   488     EInternals = TRACE_INTERNALS,

   489     EDump = TRACE_DUMP,

   490     EFlow = TRACE_FLOW,

   491     ESystemCharacteristicMetrics = TRACE_PERFORMANCE,

   492     EAdhoc = TRACE_ADHOC,

   493     EClassificationAllHighWaterMark

   494     };

   495 

   496 // Check high water mark for the 'All' classification range

   497 __ASSERT_COMPILE(EClassificationAllHighWaterMark <= EOstReservedRangeLast + 1);

   498 

   499 /**

   500  * @deprecated Use enumerations from TGroupIdReserved instead

   501  * @see TGroupId

   502  * @see TGroupIdRange

   503  * @see EOstReservedRangeFirst

   504  */

   505 enum TClassificationSymbianTwo

   506 	{

   507 	EClassificationExtension = TRACE_EXTENSION,

   508 	EClassificationSymbianTwoHighWaterMark

   509 	};

   510 

   511 // Check high water marks for the Symbian Two classification range

   512 __ASSERT_COMPILE(EClassificationSymbianTwoHighWaterMark <= EOstReservedRangeLast + 1);

   513 

   514 /**

   515  * @deprecated Use enumerations from TGroupIdTesting instead

   516  * @see TGroupId

   517  * @see TGroupIdRange

   518  * @see ETestingRangeFirst

   519  * @test

   520  */

   521 enum TClassificationTesting

   522 	{

   523 	ETesting1 = TRACE_TESTING1,

   524 	ETesting2 = TRACE_TESTING2,

   525 	EClassificationTestingHighWaterMark,

   526 	};

   527 

   528 // Check high water marks for classification ranges

   529 __ASSERT_COMPILE(EClassificationTestingHighWaterMark <= ETestingRangeLast + 1);

   530 

   531 

   532 #endif //OPENSYSTEMTRACE_TYPES_H