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

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // Trace API

    15 //

    16 

    17 #ifndef OPENSYSTEMTRACEV2_H

    18 #define OPENSYSTEMTRACEV2_H

    19 

    20 #include <opensystemtrace_types.h>

    21 

    22 

    23 /**

    24 Methods for tracing from user side.

    25 

    26 These methods are used to output trace packets.

    27 Each trace packet consists of attributes and the user defined payload.

    28 

    29 In order to output trace packets, tracing needs to be

    30 included and enabled at compile time in the executable,

    31 as well as be filtered at run-time.

    32 

    33 Note:

    34 OSTv2 does not enforce any security. It is the developer's responsibility

    35 to ensure that trace packets do not contain any sensitive information that

    36 may undermine platform security.

    37 

    38 @file

    39 @publishedPartner

    40 @prototype

    41 */

    42 

    43 /**

    44 Class used to encapsulate the context of a trace point.

    45 For more information about the attributes please @see opensystemtrace_types.h.

    46 

    47 The attributes in @see TTraceContext are used to identify and filter the trace packet.

    48 @see opensystemtrace.mmh

    49 @see RUlogger for information on how to filter at run-time

    50 

    51 @deprecated

    52 */

    53 NONSHARABLE_CLASS(TTraceContext)

    54     {

    55 public:

    56     inline TTraceContext(const TGroupId aGroupId);

    57     inline TTraceContext(const TGroupId aGroupId, const THasThreadIdentification aHasThreadIdentification, const THasProgramCounter aHasProgramCounter);

    58 

    59     inline TTraceContext(const TComponentId aComponentId, const TGroupId aGroupId);

    60     inline TTraceContext(const TComponentId aComponentId, const TGroupId aGroupId, const THasThreadIdentification aHasThreadIdentification, const THasProgramCounter aHasProgramCounter);

    61 

    62     IMPORT_C TComponentId               ComponentId() const;

    63     IMPORT_C TClassification            Classification() const;

    64     IMPORT_C TGroupId                   GroupId() const;

    65     IMPORT_C THasThreadIdentification   HasThreadIdentification() const;

    66     IMPORT_C THasProgramCounter         HasProgramCounter() const;

    67     IMPORT_C static TComponentId        DefaultComponentId();

    68 private:

    69     inline TTraceContext(){};

    70 private:

    71     TComponentId                iComponentId;               ///<@see TComponentId

    72     TGroupId                    iGroupId;                   ///<@see TGroupId

    73     THasThreadIdentification    iHasThreadIdentification;   ///<@see THasThreadIdentification

    74     THasProgramCounter          iHasProgramCounter;         ///<@see THasProgramCounter

    75     TUint32                     iReserved1;                 //Reserved for future use

    76     TUint32                     iReserved2;                 //Reserved for future use

    77     };

    78 

    79 	IMPORT_C TBool OstPrint(const TTraceContext& aContext, const TDesC8& aDes);

    80     IMPORT_C TBool OstPrintf(const TTraceContext& aContext, const char* aFmt, ...);

    81     IMPORT_C TBool OstPrintf(const TTraceContext& aContext, TRefByValue<const TDesC8> aFmt,...);

    82     #ifndef  __KERNEL_MODE__

    83     IMPORT_C TBool OstPrint(const TTraceContext& aContext, const TDesC16& aDes);

    84     IMPORT_C TBool OstPrintf(const TTraceContext& aContext, TRefByValue<const TDesC16> aFmt,...);

    85     #endif //__KERNEL_MODE__

    86 

    87     IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId);

    88     IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TUint8 aData);

    89     IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TUint16 aData);

    90     IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TUint32 aData);

    91     IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TUint32 aData1, const TUint32 aData2);

    92     IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TDesC8& aData);

    93     #ifndef __KERNEL_MODE__

    94     IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TDesC16& aData);

    95     #endif

    96     template<typename T>

    97     static inline TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const T& aData);

    98     IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TAny* aData, const TInt aDataSize);

    99 

   100     IMPORT_C TBool IsTraceActive(const TTraceContext& aContext);

   101 

   102 

   103 /**

   104 The following trace APIs require a TraceCompiler to be present in the build system. 

   105 This TraceCompiler is used to generate additional information for each trace point 

   106 in order for traces to be generated at runtime.

   107 */

   108 

   109 #include <opensystemtrace.inl>

   110 

   111 // Macros

   112 

   113 /**

   114 Preprocessor category for all traces off.

   115 This should not be used from traces

   116 */

   117 #define OST_TRACE_CATEGORY_NONE 0x00000000

   118 

   119 /**

   120 Preprocessor category for production traces

   121 */

   122 #define OST_TRACE_CATEGORY_PRODUCTION 0x00000001

   123 

   124 /**

   125 Preprocessor category for RnD traces

   126 */

   127 #define OST_TRACE_CATEGORY_RND 0x00000002

   128 

   129 /**

   130 Preprocessor category for performance measurement traces

   131 */

   132 #define OST_TRACE_CATEGORY_PERFORMANCE_MEASUREMENT 0x00000004

   133 

   134 /**

   135 Preprocessor level for all traces on.

   136 This should not be used from traces

   137 */

   138 #define OST_TRACE_CATEGORY_ALL 0xFFFFFFFF

   139 

   140 

   141 /**

   142 A flag, which specifies if the compiler has been run for the component

   143 */

   144 #if defined( OST_TRACE_COMPILER_IN_USE )

   145 

   146 

   147 /**

   148 The default preprocessor category is RND

   149 Component may override this by defining

   150 OST_TRACE_CATEGORY before including this file

   151 */

   152 #if !defined( OST_TRACE_CATEGORY )

   153 #define OST_TRACE_CATEGORY OST_TRACE_CATEGORY_RND

   154 #endif

   155 

   156 /**

   157 Trace with no parameters

   158 

   159 @param aCategory Preprocessor category for the trace

   160 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   161                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   162                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   163 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   164 @param aTraceText The trace text, which is parsed by the trace compiler.

   165                   The text itself is not sent in the trace packet

   166 */

   167 #define OstTraceDef0( aCategory, aGroupName, aTraceName, aTraceText ) \

   168     do {if ( aCategory & OST_TRACE_CATEGORY ) \

   169     BTraceFilteredContext8( EXTRACT_GROUP_ID(aTraceName), \

   170                         EOstTrace, \

   171                         KOstTraceComponentID, \

   172                         aTraceName );} while (0)

   173 

   174 

   175 /**

   176 Trace with one 32-bit parameter

   177 

   178 @param aCategory Preprocessor category for the trace

   179 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   180                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   181                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   182 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   183 @param aTraceText The trace text, which is parsed by the trace compiler.

   184                   The text itself is not sent in the trace packet

   185 @param aParam The 32-bit value to be traced

   186 */

   187 #define OstTraceDef1( aCategory, aGroupName, aTraceName, aTraceText, aParam ) \

   188     do {if ( aCategory & OST_TRACE_CATEGORY ) \

   189     BTraceFilteredContext12( EXTRACT_GROUP_ID(aTraceName), \

   190                          EOstTrace, \

   191                          KOstTraceComponentID, \

   192                          aTraceName, \

   193                          aParam );} while (0)

   194 

   195 

   196 /**

   197 Trace with more than 32 bits of data

   198 

   199 @param aCategory Preprocessor category for the trace

   200 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   201                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   202                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   203 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   204 @param aTraceText The trace text, which is parsed by the trace compiler.

   205                   The text itself is not sent in the trace packet

   206 @param aPtr Pointer to the data to be traced

   207 @param aLength Length of the data to be traced

   208 */

   209 #define OstTraceDefData( aCategory, aGroupName, aTraceName, aTraceText, aPtr, aLength ) \

   210     do {if ( aCategory & OST_TRACE_CATEGORY ) \

   211         OstSendNBytes( EXTRACT_GROUP_ID(aTraceName), \

   212                        EOstTrace, \

   213                        KOstTraceComponentID, \

   214                        aTraceName, \

   215                        aPtr, \

   216                        aLength );} while (0)

   217 

   218 

   219 /**

   220 Trace with one parameter that is not 32-bit integer. This calls OstTraceGen1,

   221 which is generated by the trace compiler. The generated function will pack the

   222 parameter into a stack-allocated buffer and call OstTraceData with the buffer.

   223 

   224 @param aCategory Preprocessor category for the trace

   225 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   226                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   227                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   228 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   229 @param aTraceText The trace text, which is parsed by the trace compiler.

   230                   The text itself is not sent in the trace packet

   231 @param aParam The parameter to be traced

   232 */

   233 #define OstTraceDefExt1( aCategory, aGroupName, aTraceName, aTraceText, aParam ) \

   234     do {if ( aCategory & OST_TRACE_CATEGORY ) \

   235         OstTraceGen1( aTraceName, aParam );} while (0)

   236 

   237 

   238 /**

   239 Trace with two parameters. This calls OstTraceGen2, which is generated by trace compiler.

   240 The generated function will pack the parameters into a stack-allocated buffer and

   241 call OstTraceData with the buffer.

   242 

   243 @param aCategory Preprocessor category for the trace

   244 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   245                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   246                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   247 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   248 @param aTraceText The trace text, which is parsed by the trace compiler.

   249                   The text itself is not sent in the trace packet

   250 @param aParam1 The first parameter to be traced

   251 @param aParam2 The second parameter to be traced

   252 */

   253 #define OstTraceDefExt2( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2 ) \

   254     do {if ( aCategory & OST_TRACE_CATEGORY ) \

   255         OstTraceGen2( aTraceName, aParam1, aParam2 );} while (0)

   256 

   257 

   258 /**

   259 Trace with three parameters. This calls OstTraceGen3, which is generated by trace compiler.

   260 The generated function will pack the parameters into a stack-allocated buffer and

   261 call OstTraceData with the buffer.

   262 

   263 @param aCategory Preprocessor category for the trace

   264 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   265                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   266                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   267 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   268 @param aTraceText The trace text, which is parsed by the trace compiler.

   269                   The text itself is not sent in the trace packet

   270 @param aParam1 The first parameter to be traced

   271 @param aParam2 The second parameter to be traced

   272 @param aParam3 The third parameter to be traced

   273 */

   274 #define OstTraceDefExt3( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 ) \

   275     do {if ( aCategory & OST_TRACE_CATEGORY ) \

   276         OstTraceGen3( aTraceName, aParam1, aParam2, aParam3 );} while (0)

   277 

   278 

   279 /**

   280 Trace with four parameters. This calls OstTraceGen4, which is generated by trace compiler.

   281 The generated function will pack the parameters into a stack-allocated buffer and

   282 call OstTraceData with the buffer.

   283 

   284 @param aCategory Preprocessor category for the trace

   285 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   286                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   287                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   288 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   289 @param aTraceText The trace text, which is parsed by the trace compiler.

   290                   The text itself is not sent in the trace packet

   291 @param aParam1 The first parameter to be traced

   292 @param aParam2 The second parameter to be traced

   293 @param aParam3 The third parameter to be traced

   294 @param aParam4 The fourth parameter to be traced

   295 */

   296 #define OstTraceDefExt4( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 ) \

   297     do {if ( aCategory & OST_TRACE_CATEGORY ) \

   298         OstTraceGen4( aTraceName, aParam1, aParam2, aParam3, aParam4 );} while (0)

   299 

   300 

   301 /**

   302 Trace with five parameters. This calls OstTraceGen5, which is generated by trace compiler.

   303 The generated function will pack the parameters into a stack-allocated buffer and

   304 call OstTraceData with the buffer.

   305 

   306 @param aCategory Preprocessor category for the trace

   307 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   308                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   309                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   310 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   311 @param aTraceText The trace text, which is parsed by the trace compiler.

   312                   The text itself is not sent in the trace packet

   313 @param aParam1 The first parameter to be traced

   314 @param aParam2 The second parameter to be traced

   315 @param aParam3 The third parameter to be traced

   316 @param aParam4 The fourth parameter to be traced

   317 @param aParam5 The fifth parameter to be traced

   318 */

   319 #define OstTraceDefExt5( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 ) \

   320     do {if ( aCategory & OST_TRACE_CATEGORY ) \

   321         OstTraceGen5( aTraceName, aParam1, aParam2, aParam3, aParam4, aParam5 );} while (0)

   322 

   323 

   324 /**

   325 *************** Trace macros which use RnD as default preprocessor category ***************

   326 */

   327 

   328 /**

   329 RnD trace with no parameters

   330 

   331 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   332                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   333                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   334 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   335 @param aTraceText The trace text, which is parsed by the trace compiler.

   336                   The text itself is not sent in the trace packet

   337 */

   338 #define OstTrace0( aGroupName, aTraceName, aTraceText ) \

   339     OstTraceDef0( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText )

   340 

   341 

   342 /**

   343 RnD trace with one 32-bit parameter

   344 

   345 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   346                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   347                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   348 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   349 @param aTraceText The trace text, which is parsed by the trace compiler.

   350                   The text itself is not sent in the trace packet

   351 @param aParam The 32-bit value to be traced

   352 */

   353 #define OstTrace1( aGroupName, aTraceName, aTraceText, aParam ) \

   354     OstTraceDef1( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam )

   355 

   356 

   357 /**

   358 RnD trace with more than 32 bits of data

   359 

   360 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   361                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   362                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   363 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   364 @param aTraceText The trace text, which is parsed by the trace compiler.

   365                   The text itself is not sent in the trace packet

   366 @param aPtr Pointer to the data to be traced

   367 @param aLength Length of the data to be traced

   368 */

   369 #define OstTraceData( aGroupName, aTraceName, aTraceText, aPtr, aLength ) \

   370     OstTraceDefData( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aPtr, aLength )

   371 

   372 

   373 /**

   374 RnD trace with one parameter that is not 32-bit integer. This calls OstTraceGen1,

   375 which is generated by the trace compiler. The generated function will pack the

   376 parameter into a stack-allocated buffer and call OstTraceData with the buffer.

   377 

   378 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   379                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   380                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   381 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   382 @param aTraceText The trace text, which is parsed by the trace compiler.

   383                   The text itself is not sent in the trace packet

   384 @param aParam The parameter to be traced

   385 */

   386 #define OstTraceExt1( aGroupName, aTraceName, aTraceText, aParam ) \

   387     OstTraceDefExt1( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam )

   388 

   389 

   390 /**

   391 RnD trace with two parameters. This calls OstTraceGen2, which is generated by trace compiler.

   392 The generated function will pack the parameters into a stack-allocated buffer and

   393 call OstTraceData with the buffer.

   394 

   395 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   396                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   397                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   398 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   399 @param aTraceText The trace text, which is parsed by the trace compiler.

   400                   The text itself is not sent in the trace packet

   401 @param aParam1 The first parameter to be traced

   402 @param aParam2 The second parameter to be traced

   403 */

   404 #define OstTraceExt2( aGroupName, aTraceName, aTraceText, aParam1, aParam2 ) \

   405     OstTraceDefExt2( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam1, aParam2 )

   406 

   407 

   408 /**

   409 RnD trace with three parameters. This calls OstTraceGen3, which is generated by trace compiler.

   410 The generated function will pack the parameters into a stack-allocated buffer and

   411 call OstTraceData with the buffer.

   412 

   413 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   414                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   415                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   416 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   417 @param aTraceText The trace text, which is parsed by the trace compiler.

   418                   The text itself is not sent in the trace packet

   419 @param aParam1 The first parameter to be traced

   420 @param aParam2 The second parameter to be traced

   421 @param aParam3 The third parameter to be traced

   422 */

   423 #define OstTraceExt3( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 ) \

   424     OstTraceDefExt3( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 )

   425 

   426 

   427 /**

   428 RnD trace with four parameters. This calls OstTraceGen4, which is generated by trace compiler.

   429 The generated function will pack the parameters into a stack-allocated buffer and

   430 call OstTraceData with the buffer.

   431 

   432 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   433                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   434                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   435 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   436 @param aTraceText The trace text, which is parsed by the trace compiler.

   437                   The text itself is not sent in the trace packet

   438 @param aParam1 The first parameter to be traced

   439 @param aParam2 The second parameter to be traced

   440 @param aParam3 The third parameter to be traced

   441 @param aParam4 The fourth parameter to be traced

   442 */

   443 #define OstTraceExt4( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 ) \

   444     OstTraceDefExt4( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 )

   445 

   446 

   447 /**

   448 RnD trace with five parameters. This calls OstTraceGen5, which is generated by trace compiler.

   449 The generated function will pack the parameters into a stack-allocated buffer and

   450 call OstTraceData with the buffer.

   451 

   452 @param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

   453                   Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

   454                   (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

   455 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   456 @param aTraceText The trace text, which is parsed by the trace compiler.

   457                   The text itself is not sent in the trace packet

   458 @param aParam1 The first parameter to be traced

   459 @param aParam2 The second parameter to be traced

   460 @param aParam3 The third parameter to be traced

   461 @param aParam4 The fourth parameter to be traced

   462 @param aParam5 The fifth parameter to be traced

   463 */

   464 #define OstTraceExt5( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 ) \

   465     OstTraceDefExt5( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 )

   466 

   467 

   468 /**

   469 Function entry trace without extra parameters.

   470 The trace is mapped to TRACE_FLOW or TRACE_API group by the trace compiler

   471 

   472 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   473 */

   474 #define OstTraceFunctionEntry0( aTraceName ) \

   475     do {if ( OST_TRACE_CATEGORY_RND & OST_TRACE_CATEGORY ) \

   476     BTraceFilteredContext8( EXTRACT_GROUP_ID(aTraceName), \

   477                         EOstTrace, \

   478                         KOstTraceComponentID, \

   479                         aTraceName );} while (0)

   480 

   481 

   482 /**

   483 Function entry trace with a parameter representing the instance identifier.

   484 The trace is mapped to TRACE_FLOW or TRACE_API group by the trace compiler

   485 

   486 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   487 @param aInstance The instance identifier, for example "this" pointer

   488 */

   489 #define OstTraceFunctionEntry1( aTraceName, aInstance ) \

   490     do {if ( OST_TRACE_CATEGORY_RND & OST_TRACE_CATEGORY ) \

   491     BTraceFilteredContext12( EXTRACT_GROUP_ID(aTraceName), \

   492                          EOstTrace, \

   493                          KOstTraceComponentID, \

   494                          aTraceName, \

   495                          (TUint32) aInstance );} while (0)

   496 

   497 

   498 /**

   499 Function entry trace, which traces function parameters.

   500 The trace is mapped to TRACE_FLOW or TRACE_API group by the trace compiler

   501 

   502 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   503 @param aInstance Name of the instance identifier

   504 */

   505 #define OstTraceFunctionEntryExt( aTraceName, aInstance ) \

   506     do {if ( OST_TRACE_CATEGORY_RND & OST_TRACE_CATEGORY ) \

   507         OstTraceGenExt( aTraceName, ( TUint )aInstance );} while (0)

   508 

   509 

   510 /**

   511 Function exit trace without extra parameters.

   512 The trace is mapped to TRACE_FLOW or TRACE_API group by the trace compiler

   513 

   514 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   515 */

   516 #define OstTraceFunctionExit0( aTraceName ) \

   517     do {if ( OST_TRACE_CATEGORY_RND & OST_TRACE_CATEGORY ) \

   518     BTraceFilteredContext8( EXTRACT_GROUP_ID(aTraceName), \

   519                         EOstTrace, \

   520                         KOstTraceComponentID, \

   521                         aTraceName );} while (0)

   522 

   523 

   524 /**

   525 Function exit trace with a parameter representing the instance identifier.

   526 The trace is mapped to TRACE_FLOW or TRACE_API group by the trace compiler

   527 

   528 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   529 @param aInstance The instance identifier, for example "this" pointer

   530 */

   531 #define OstTraceFunctionExit1( aTraceName, aInstance ) \

   532     do {if ( OST_TRACE_CATEGORY_RND & OST_TRACE_CATEGORY ) \

   533     BTraceFilteredContext12( EXTRACT_GROUP_ID(aTraceName), \

   534                          EOstTrace, \

   535                          KOstTraceComponentID, \

   536                          aTraceName, \

   537                          (TUint32) aInstance );} while (0)

   538 

   539 

   540 /**

   541 Function exit trace with a parameters representing the instance identifier and return value.

   542 The trace is mapped to TRACE_FLOW or TRACE_API group by the trace compiler

   543 

   544 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   545 @param aInstance The instance identifier, for example "this" pointer

   546 @param aRetval The function return value

   547 */

   548 #define OstTraceFunctionExitExt( aTraceName, aInstance, aRetval ) \

   549     do {if ( OST_TRACE_CATEGORY_RND & OST_TRACE_CATEGORY ) \

   550         OstTraceGen2( aTraceName, ( TUint )aInstance, aRetval );} while (0)

   551 

   552 

   553 /**

   554 Performance measurement event start trace without extra parameters.

   555 The trace is mapped to TRACE_PERFORMANCE group by the trace compiler

   556 

   557 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   558 @param aEventName The name of the event. A corresponding OstTraceEventStop call must be made later in code

   559 */

   560 #define OstTraceEventStart0( aTraceName, aEventName ) \

   561         OstTraceDef1( OST_TRACE_CATEGORY_RND, "TRACE_PERFORMANCE", aTraceName, null, (TInt32)1 )

   562 

   563 

   564 /**

   565 Performance measurement event start trace with single 32-bit parameter.

   566 The trace is mapped to TRACE_PERFORMANCE group by the trace compiler

   567 

   568 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   569 @param aEventName The name of the event. A corresponding OstTraceEventStop call must be made later in code

   570 @param aParam The parameter to be associated to the event

   571 */

   572 #define OstTraceEventStart1( aTraceName, aEventName, aParam ) \

   573         OstTraceDef1( OST_TRACE_CATEGORY_RND, "TRACE_PERFORMANCE", aTraceName, null, aParam )

   574 

   575 

   576 /**

   577 Performance measurement event end trace.

   578 The trace is mapped to TRACE_PERFORMANCE group by the trace compiler

   579 

   580 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   581 @param aEventName The name of the event. Must match a name passed to OstTraceEventStart

   582 @param aStartTraceName Event start trace name. Must match a Trace Name of OstTraceEventStart trace

   583 */

   584 #define OstTraceEventStop( aTraceName, aEventName, aStartTraceName ) \

   585         OstTraceDefExt2( OST_TRACE_CATEGORY_RND, "TRACE_PERFORMANCE", aTraceName, null, (TInt32)0, (TUint32)(aStartTraceName & 0xFFFF) ) 

   586 

   587 

   588 /**

   589 State transition event.

   590 The trace is mapped to TRACE_STATE group by the trace compiler

   591 

   592 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   593 @param aStateName The name of the state, literal string (for example "name")

   594 @param aNewState The new value for the state, literal string (for example "value")

   595 */

   596 #define OstTraceState0( aTraceName, aStateName, aNewState ) \

   597         OstTraceDefExt2( OST_TRACE_CATEGORY_RND, "TRACE_STATE", aTraceName, null, _L8(aStateName), _L8(aNewState) ) 

   598 

   599 

   600 /**

   601 State transition event with instance identifier.

   602 The trace is mapped to TRACE_STATE group by the trace compiler

   603 

   604 @param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

   605 @param aStateName The name of the state, literal string (for example "name")

   606 @param aNewState The new value for the state, literal string (for example "value")

   607 @param aInstance The instance identifier, for example "this" pointer

   608 */

   609 #define OstTraceState1( aTraceName, aStateName, aNewState, aInstance ) \

   610         OstTraceDefExt3( OST_TRACE_CATEGORY_RND, "TRACE_STATE", aTraceName, null, _L8(aStateName), _L8(aNewState), (TUint32) aInstance ) 

   611        

   612 #else // OST_TRACE_COMPILER_IN_USE

   613 

   614 /**

   615 API is defined empty if the trace compiler has not been run

   616 */

   617 

   618 #define OstTraceDef0( aCategory, aGroupName, aTraceName, aTraceText )

   619 #define OstTraceDef1( aCategory, aGroupName, aTraceName, aTraceText, aParam )

   620 #define OstTraceDefData( aCategory, aGroupName, aTraceName, aTraceText, aPtr, aLength )

   621 #define OstTraceDefExt1( aCategory, aGroupName, aTraceName, aTraceText, aParam )

   622 #define OstTraceDefExt2( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2 )

   623 #define OstTraceDefExt3( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 )

   624 #define OstTraceDefExt4( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 )

   625 #define OstTraceDefExt5( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 )

   626 

   627 #define OstTrace0( aGroupName, aTraceName, aTraceText )

   628 #define OstTrace1( aGroupName, aTraceName, aTraceText, aParam )

   629 #define OstTraceData( aGroupName, aTraceName, aTraceText, aPtr, aLength )

   630 #define OstTraceExt1( aGroupName, aTraceName, aTraceText, aParam )

   631 #define OstTraceExt2( aGroupName, aTraceName, aTraceText, aParam1, aParam2 )

   632 #define OstTraceExt3( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 )

   633 #define OstTraceExt4( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 )

   634 #define OstTraceExt5( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 )

   635 

   636 #define OstTraceFunctionEntry0( aTraceName )

   637 #define OstTraceFunctionEntry1( aTraceName, aInstance )

   638 #define OstTraceFunctionEntryExt(aTraceName, aInstance)

   639 #define OstTraceFunctionExit0( aTraceName )

   640 #define OstTraceFunctionExit1( aTraceName, aInstance )

   641 #define OstTraceEventStart0( aTraceName, aEventName )

   642 #define OstTraceEventStart1( aTraceName, aEventName, aParam )

   643 #define OstTraceFunctionExitExt(aTraceName, aInstance, aRetval)

   644 #define OstTraceEventStop( aTraceName, aEventName, aStartTraceName )

   645 #define OstTraceState0( aTraceName, aStateName, aNewState )

   646 #define OstTraceState1( aTraceName, aStateName, aNewState, aInstance )

   647 

   648 #endif // OST_TRACE_COMPILER_IN_USE

   649 

   650 

   651 // Data types

   652 

   653 /**

   654 BTrace sub-category IDs for OpenSystemTrace category

   655 */

   656 enum TSubcategoryOpenSystemTrace

   657     {

   658     /**

   659      * Normal trace

   660      */

   661     EOstTrace                   = 0,

   662 

   663     /**

   664      * Queries if trace is active without sending it

   665      */

   666     EOstTraceActivationQuery    = 1

   667     };

   668 

   669 // Forward declarations

   670 

   671 /**

   672 Template class for array parameter types

   673 For example, to wrap an integer array to a trace:

   674 TInt arr[5];

   675 OstTraceExt( GRP, TRC, "Array: %{int32[]}", TOstArray< TInt >( arr, 5 ) );

   676 */

   677 template< class T >

   678 class TOstArray

   679     {

   680 public:

   681     /**

   682      * Constructor

   683      *

   684      * @param aArray the array data

   685      * @param aLength the number of elements in the array

   686      */

   687     TOstArray( const T* aArray, TInt aLength ) : iArray( aArray ), iLength( aLength ) {}

   688 

   689     /**

   690      * Gets the array data pointer.

   691      * Used from the functions generated by trace compiler

   692      * 

   693      * @return The array data pointer.

   694      */

   695     const T* Ptr() const { return iArray; }

   696 

   697     /**

   698      * Gets the number of elements in the array.

   699      * Used from the functions generated by trace compiler

   700      * 

   701      * @return The number of elements in the array.

   702      */

   703     TInt Length() const { return iLength; }

   704 

   705     /**

   706      * Gets the number of bytes occupied by the array.

   707      * Used from the functions generated by trace compiler

   708      * 

   709      * @return The number of bytes occupied by the array.

   710      */

   711     TInt Size() const { return sizeof( T ) * iLength; }

   712 

   713 private:

   714     /**

   715      * Array data

   716      */

   717     const T* iArray;

   718 

   719     /**

   720      * Array length, as number of elements

   721      */

   722     TInt iLength;

   723     };

   724 

   725 

   726 // Class declaration

   727 

   728 #endif //OPENSYSTEMTRACEV2_H