1 /*

     2 * ============================================================================

     3 *  Name        : bluetoothtrace.h

     4 *  Part of     : BluetoothUI / bluetoothuimodel       *** Info from the SWAD

     5 *  Description : API declaration of run-time debug tracing

     6 *

     7 *  Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies).

     8 *  All rights reserved.

     9 *  This component and the accompanying materials are made available

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

    11 *  which accompanies this distribution, and is available

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

    13 *

    14 *  Initial Contributors:

    15 *  Nokia Corporation - initial contribution.

    16 *

    17 *  Contributors:

    18 *  Nokia Corporation

    19 * ============================================================================

    20 * Template version: 4.2

    21 */

    22 

    23 #ifndef BLUETOOTHTRACE_H

    24 #define BLUETOOTHTRACE_H

    25 

    26 #include <e32base.h>

    27 #include "traceconfig.h"

    28 

    29 /*

    30  * Common tracing utility definition to be used by Bluetooth projects.

    31  * The configuration is loaded from traceconfig.h which shall be private for

    32  * each individual project.

    33  * 

    34  * In this utility, a set of OST-alike tracing macros are defined. 

    35  * (The purpose is to ease migration to OST in future.)

    36  * 

    37  * Individual project can also define new macros based on this utility in

    38  * its own space.

    39  * 

    40  */

    41 

    42 #ifdef BLUETOOTHTRACE_ENABLED

    43 

    44 #ifdef BLUETOOTHTRACE_MEDIA_OST

    45 

    46 /**

    47  * Convert own macros to OST macros when OST tracing is used.

    48  * In OST tracing, aTraceName must be a unique identifier in scope of a module. 

    49  * Thus many OST compiling errors may occur if the same TraceName is used in multiple

    50  * tracing lines where tracing is miigrated from non-OST to OST. 

    51  * The fix is to renaming the TraceName:s to be unique.

    52  */

    53 #include <OpenSystemTrace.h>

    54 

    55 #define BOstrace0( aGroupName, aTraceName, aTraceText ) \

    56     OstTrace0( aGroupName, aTraceName, aTraceText )

    57 

    58 #define BOstrace1( aGroupName, aTraceName, aTraceText, aParam ) \

    59     OstTrace1( aGroupName, aTraceName, aTraceText, aParam )

    60 

    61 #define BOstraceData( aGroupName, aTraceName, aTraceText, aPtr, aLength ) \

    62     OstTraceData( aGroupName, aTraceName, aTraceText, aPtr, aLength )

    63 

    64 #define BOstraceExt1( aGroupName, aTraceName, aTraceText, aParam ) \

    65     OstTraceExt1( aGroupName, aTraceName, aTraceText, aParam )

    66 

    67 #define BOstraceExt2( aGroupName, aTraceName, aTraceText, aParam1, aParam2 ) \

    68     OstTraceExt2( aGroupName, aTraceName, aTraceText, aParam1, aParam2 )

    69 

    70 #define BOstraceExt3( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 ) \

    71     OstTraceExt3( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 )

    72 

    73 #define BOstraceExt4( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 ) \

    74     OstTraceExt4( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 )

    75 

    76 #define BOstraceExt5( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 ) \

    77     OstTraceExt5( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 )

    78 

    79 #define BOstraceFunctionEntry0( aTraceName ) \

    80     OstTraceFunctionEntry0( aTraceName )

    81 

    82 #define BOstraceFunctionEntry1( aTraceName, aInstance ) \

    83     OstTraceFunctionEntry1( aTraceName, aInstance )

    84 

    85 #define BOstraceFunctionEntryExt(aTraceName, aInstance, aArg) \

    86     OstTraceFunctionEntryExt(aTraceName, aInstance, aArg)

    87 

    88 #define BOstraceFunctionExit0( aTraceName ) \ 

    89     OstTraceFunctionExit0( aTraceName )

    90 

    91 #define BOstraceFunctionExit1( aTraceName, aInstance ) \

    92     OstTraceFunctionExit1( aTraceName, aInstance )

    93 

    94 #define BOstraceFunctionExitExt(aTraceName, aInstance, aRetval) \

    95     OstTraceFunctionExitExt(aTraceName, aInstance, aRetval)

    96     

    97 #define BOstraceEventStart0( aTraceName, aEventName ) \

    98     OstTraceEventStart0( aTraceName, aEventName )

    99     

   100 #define BOstraceEventStart1( aTraceName, aEventName, aParam ) \

   101     OstTraceEventStart1( aTraceName, aEventName, aParam )

   102 

   103 #define BOstraceEventStop( aTraceName, aEventName ) \

   104     OstTraceEventStop( aTraceName, aEventName )

   105 

   106 #define BOstraceState0( aTraceName, aStateName, aNewState ) \

   107     OstTraceState0( aTraceName, aStateName, aNewState )

   108 

   109 #define BOstraceState1( aTraceName, aStateName, aNewState, aInstance ) \

   110     OstTraceState1( aTraceName, aStateName, aNewState, aInstance )

   111     

   112 #else  // BLUETOOTHTRACE_MEDIA_OST

   113 

   114 #ifdef BLUETOOTHTRACE_MEDIA_FILE

   115 #include <flogger.h>

   116 #else   

   117 #include <e32debug.h>

   118 #endif

   119 

   120 /**

   121  * When tracing compilation with OST is disabled, the TraceName in each OST trace line

   122  * is ignored, that is, the Trace Names are not checked at compiling time, neither

   123  * are they written into the specified trace output media.

   124  */

   125     

   126 /**

   127  * Handlers below are used for tolerating overflow of formatting strings.

   128  * to trucate rather than panic the caller.

   129  */

   130 NONSHARABLE_CLASS( TBtTraceOflowTruncate8 ) : public TDes8Overflow

   131     {

   132 public:

   133     void Overflow( TDes8& /*aDes*/ ) {}

   134     };

   135 

   136 NONSHARABLE_CLASS( TBtTraceOflowTruncate16 ) : public TDes16Overflow

   137     {

   138 public:

   139     void Overflow( TDes16& /*aDes*/ ) {}

   140     };

   141 

   142 /**

   143  * internal tracing implementation, do not use it out of this file.

   144  */

   145 inline void Trace(const TDesC &trGrp, const TDesC &trTxt)

   146 {

   147     _LIT(Format, "%S%S%S");

   148     TBuf16<0x180> str; 

   149     TPtrC cp(KComponentName);

   150     str.Format(Format, &cp, &trGrp, &trTxt);

   151 #ifdef BLUETOOTHTRACE_MEDIA_FILE

   152     RFileLogger::WriteFormat( KLogDir, KLogFile, EFileLoggingModeAppend, str);

   153 #else

   154     RDebug::Print( str );

   155 #endif

   156 }

   157 

   158 /*

   159  * trace with no parameters

   160  */

   161 #define BOstrace0( aGroupName, aTraceName, aTraceText ) \

   162 {\

   163     _LIT(TrGrp, aGroupName); _LIT(TrTxt, aTraceText); \

   164     Trace( TrGrp, TrTxt ); \

   165 }

   166 

   167 /*

   168  * trace with one 32-bit parameter

   169  */

   170 #define BOstrace1( aGroupName, aTraceName, aTraceText, aParam ) \

   171 {\

   172     _LIT(TrGrp, aGroupName); _LIT(TrTxt, aTraceText); \

   173     TBuf<512> buf; TBtTraceOflowTruncate16 overflow; \

   174     buf.AppendFormat(TrTxt, &overflow, aParam); \

   175     Trace( TrGrp, buf ); \

   176 }

   177 

   178 /*

   179  * trace with more than 32 bits of data. Not supported

   180  */

   181 #define BOstraceData( aGroupName, aTraceName, aTraceText, aPtr, aLength ) 

   182 

   183 /*

   184  * trace with one parameter that is not 32-bit integer

   185  */

   186 #define BOstraceExt1( aGroupName, aTraceName, aTraceText, aParam ) \

   187     BOstrace1( aGroupName, aTraceName, aTraceText, aParam )

   188 

   189 /*

   190  * trace with two parameters.

   191  */

   192 #define BOstraceExt2( aGroupName, aTraceName, aTraceText, aParam1, aParam2 ) \

   193 {\

   194     _LIT(TrGrp, aGroupName); _LIT(TrTxt, aTraceText); \

   195     TBuf<512> buf; TBtTraceOflowTruncate16 overflow; \

   196     buf.AppendFormat(TrTxt, &overflow, aParam1, aParam2); \

   197     Trace( TrGrp, buf ); \

   198 }

   199 

   200 /*

   201  * trace with three parameters.

   202  */

   203 #define BOstraceExt3( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 ) \

   204 {\

   205     _LIT(TrGrp, aGroupName); _LIT(TrTxt, aTraceText); \

   206     TBuf<512> buf; TBtTraceOflowTruncate16 overflow; \

   207     buf.AppendFormat(TrTxt, &overflow, aParam1, aParam2, aParam3); \

   208     Trace( TrGrp, buf ); \

   209 }

   210 

   211 /*

   212  * trace with four parameters

   213  */    

   214 #define BOstraceExt4( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 ) \

   215 {\

   216     _LIT(TrGrp, aGroupName); _LIT(TrTxt, aTraceText); \

   217     TBuf<512> buf; TBtTraceOflowTruncate16 overflow; \

   218     buf.AppendFormat(TrTxt, &overflow, aParam1, aParam2, aParam3, aParam4); \

   219     Trace( TrGrp, buf ); \

   220 }

   221 

   222 /*

   223  * trace with five parameters

   224  */   

   225 #define BOstraceExt5( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 ) \

   226 {\

   227     _LIT(TrGrp, aGroupName); _LIT(TrTxt, aTraceText); \

   228     TBuf<512> buf; TBtTraceOflowTruncate16 overflow; \

   229     buf.AppendFormat(TrTxt, &overflow, aParam1, aParam2, aParam3, aParam4, aParam5); \

   230     Trace( TrGrp, buf ); \

   231 }

   232 

   233 /*

   234  * Function entry trace without extra parameters. 

   235  * The trace is mapped to TRACE_API group.

   236  */

   237 #define BOstraceFunctionEntry0( aTraceName ) \

   238 {\

   239     _LIT(TrGrp, "[ API ]"); \

   240     TPtrC8 func( (TUint8*) __PRETTY_FUNCTION__ ); \

   241     _LIT(Entry, ">> "); \

   242     TBuf<512> buf; buf.Copy( func ); buf.Insert(0, Entry );\

   243     Trace( TrGrp, buf ); \

   244 }

   245 

   246 /*

   247  * Function entry trace with a parameter representing the instance identifier, e.g.

   248  * "this" pointer.

   249  * The trace is mapped to TRACE_API group.

   250  */

   251 #define BOstraceFunctionEntry1( aTraceName, aInstance ) \

   252 {\

   253     _LIT(TrGrp, "[ API ]");\

   254     TPtrC8 func( (TUint8*) __PRETTY_FUNCTION__ ); \

   255     _LIT(Entry, ">> "); _LIT(Fmt, " 0x%X(%d)"); \

   256     TBuf<512> buf; buf.Copy( func ); buf.Insert(0, Entry); \

   257     TBtTraceOflowTruncate16 overflow; \

   258     buf.AppendFormat(Fmt, &overflow, aInstance, aInstance); \

   259     Trace( TrGrp, buf ); \

   260 }

   261 

   262 /*

   263  * Function entry trace, which traces function parameters.

   264  * The trace is mapped to TRACE_API group. 

   265  */

   266 #define BOstraceFunctionEntryExt(aTraceName, aInstance, aArg) \

   267 { \

   268     _LIT(TrGrp, "[ API ]");\

   269     TPtrC8 func( (TUint8*) __PRETTY_FUNCTION__ ); \

   270     _LIT(Entry, ">> "); _LIT(Fmt, " 0x%X(%d) arg %d"); \

   271     TBuf<512> buf; buf.Copy( func );  buf.Insert(0, Entry); \

   272     TBtTraceOflowTruncate16 overflow; \

   273     buf.AppendFormat(Fmt, &overflow, aInstance, aInstance, aArg); \

   274     Trace( TrGrp, buf ); \

   275 }

   276 /*

   277  * Function exit trace without extra parameters. 

   278  * The trace is mapped to TRACE_API group.

   279  */

   280 #define BOstraceFunctionExit0( aTraceName ) \

   281 {\

   282     _LIT(TrGrp, "[ API ]"); \

   283     TPtrC8 func( (TUint8*) __PRETTY_FUNCTION__ ); \

   284     _LIT(Entry, "<< "); \

   285     TBuf<512> buf; buf.Copy( func );  buf.Insert(0, Entry); \

   286     Trace( TrGrp, buf ); \

   287 }

   288 

   289 /*

   290  * Function exit trace with a parameter representing the instance identifier

   291  * for example "this" pointer.

   292  * The trace is mapped to TRACE_API group.

   293  */

   294 #define BOstraceFunctionExit1( aTraceName, aInstance ) \

   295 {\

   296     _LIT(TrGrp, "[ API ]"); \

   297     TPtrC8 func( (TUint8*) __PRETTY_FUNCTION__ ); \

   298     _LIT(Entry, "<< "); _LIT(Fmt, " 0x%X(%d)"); \

   299     TBuf<512> buf; buf.Copy( func );  buf.Insert(0, Entry); \

   300     TBtTraceOflowTruncate16 overflow; \

   301     buf.AppendFormat(Fmt, &overflow, aInstance, aInstance); \

   302     Trace( TrGrp, buf ); \

   303 }

   304 

   305 /*

   306  * Function exit trace with parameters representing the instance identifier, 

   307  * for example "this" pointer, and return value.

   308  * The trace is mapped to TRACE_API group.

   309  */

   310 #define BOstraceFunctionExitExt(aTraceName, aInstance, aRetval) \

   311 {\

   312     _LIT(TrGrp, "[ API ]");\

   313     TPtrC8 func( (TUint8*) __PRETTY_FUNCTION__ ); \

   314     _LIT(Entry, "<< "); _LIT(Fmt, " 0x%X(%d) ret %d"); \

   315     TBuf<512> buf; buf.Copy( func );  buf.Insert(0, Entry); \

   316     TBtTraceOflowTruncate16 overflow; \

   317     buf.AppendFormat(Fmt, &overflow, aInstance, aInstance, aRetval); \

   318     Trace( TrGrp, buf ); \

   319 }

   320 

   321 /*

   322  * Performance measurement event start trace without extra parameters. 

   323  * The trace is mapped to TRACE_PERFORMANCE group.

   324  */

   325 #define BOstraceEventStart0( aTraceName, aEventName ) \

   326 {\

   327     _LIT(TrGrp, "[PFMAN]"); _LIT(EvName, aEventName); \

   328     _LIT(Entry, "[Start] "); \

   329     TBuf<512> buf(Entry); buf.Append( EvName ); \

   330     Trace( TrGrp, buf ); \

   331 }

   332 

   333 /*

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

   335  * The trace is mapped to TRACE_PERFORMANCE group.

   336  */

   337 #define BOstraceEventStart1( aTraceName, aEventName, aParam ) \

   338 {\

   339     _LIT(TrGrp, "[PFMAN]"); _LIT(EvName, aEventName); \

   340     _LIT(Entry, "[Start] %S 0x%X(%d)"); \

   341     TPtrC evt(EvName); TBuf<512> buf; \

   342     TBtTraceOflowTruncate16 overflow; \

   343     buf.AppendFormat(Entry, &overflow, &evt, aParam, aParam ); \

   344     Trace( TrGrp, buf ); \

   345 }

   346 

   347 /*

   348  * Performance measurement event end trace. 

   349  * The trace is mapped to TRACE_PERFORMANCE group.

   350  */

   351 #define BOstraceEventStop( aTraceName, aEventName ) \

   352 {\

   353     _LIT(TrGrp, "[PFMAN]"); _LIT(EvName, aEventName); \

   354     _LIT(Entry, "[Stop] "); \

   355     TBuf<512> buf(Entry); buf.Append( EvName ); \

   356     Trace( TrGrp, buf ); \

   357 }

   358 

   359 /*

   360  * State transition event.

   361  * The trace is mapped to TRACE_STATE group.

   362  */

   363 #define BOstraceState0( aTraceName, aStateName, aNewState ) \

   364 {\

   365     _LIT(TrGrp, "[STATE]"); _LIT(StName, aStateName); \

   366     _LIT(Entry, "%S 0x%X(%d)"); \

   367     TPtrC evt(StName); TBuf<512> buf; \

   368     TBtTraceOflowTruncate16 overflow; \

   369     buf.AppendFormat(Entry, &overflow, &evt, aNewState, aNewState ); \

   370     Trace( TrGrp, buf ); \

   371 }

   372 

   373 /*

   374  * State transition event with instance identifier.

   375  * The trace is mapped to TRACE_STATE group.

   376  */

   377 #define BOstraceState1( aTraceName, aStateName, aNewState, aInstance ) \

   378 {\

   379     _LIT(TrGrp, "[STATE]"); _LIT(StName, aStateName); \

   380     _LIT(Entry, "%S 0x%X(%d) instance=0x%X(%d)"); \

   381     TPtrC evt(StName); TBuf<512> buf; \

   382     TBtTraceOflowTruncate16 overflow; \

   383     buf.AppendFormat(Entry, &overflow, &evt, aNewState, aNewState, aInstance, aInstance ); \

   384     Trace( TrGrp, buf ); \

   385 }

   386 

   387 #endif // BLUETOOTHTRACE_MEDIA_OST

   388 

   389 // Extended tracing macros facilitating domain specific tracing needs:

   390 

   391 /*

   392  * A block of source code merely for tracing purpose.

   393  */

   394 #define BtTraceBlock( exp ) {exp}

   395 

   396 /*

   397  * trace macro for BT device address printing with an additional trace text. 

   398  * aParam must be TBTDevAddr type.

   399  */

   400 #define BtTraceBtAddr1( aGroupName, aTraceName, aTraceText, aParam ) \

   401 { \

   402     _LIT(TrTxt, aTraceText); TPtrC p(TrTxt); \

   403     TBuf<12> buf; \

   404     aParam.GetReadable( buf ); TPtrC p2(buf);\

   405     BOstraceExt2( aGroupName, aTraceName, "%S%S", &p, &p2 ); \

   406 }

   407 

   408 /*

   409  * trace macro for BT device address printing with no additional trace text. 

   410  * aParam must be TBTDevAddr type.

   411  */

   412 #define BtTraceBtAddr0( aGroupName, aTraceName, aParam ) \

   413 { \

   414     TBuf<12> buf; aParam.GetReadable( buf ); TPtrC p(buf); \

   415     BOstraceExt1( aGroupName, aTraceName, "%S", &p ); \

   416 }

   417 

   418 #else // BLUETOOTHTRACE_ENABLED

   419 

   420 #define BOstrace0( aGroupName, aTraceName, aTraceText )

   421 #define BOstrace1( aGroupName, aTraceName, aTraceText, aParam )

   422 #define BOstraceData( aGroupName, aTraceName, aTraceText, aPtr, aLength )

   423 #define BOstraceExt1( aGroupName, aTraceName, aTraceText, aParam )

   424 #define BOstraceExt2( aGroupName, aTraceName, aTraceText, aParam1, aParam2 )

   425 #define BOstraceExt3( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 )

   426 #define BOstraceExt4( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 )

   427 #define BOstraceExt5( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 )

   428 

   429 #define BOstraceFunctionEntry0( aTraceName )

   430 #define BOstraceFunctionEntry1( aTraceName, aInstance )

   431 #define BOstraceFunctionEntryExt(aTraceName, aInstance, aArg)

   432 #define BOstraceFunctionExit0( aTraceName )

   433 #define BOstraceFunctionExit1( aTraceName, aInstance )

   434 #define BOstraceEventStart0( aTraceName, aEventName )

   435 #define BOstraceEventStart1( aTraceName, aEventName, aParam )

   436 #define BOstraceFunctionExitExt(aTraceName, aInstance, aRetval)

   437 #define BOstraceEventStop( aTraceName, aEventName )

   438 #define BOstraceState0( aTraceName, aStateName, aNewState )

   439 #define BOstraceState1( aTraceName, aStateName, aNewState, aInstance )

   440 

   441 #define BtTraceBlock( exp )

   442 #define BtTraceBtAddr1( aGroupName, aTraceName, aTraceText, aParam )

   443 #define BtTraceBtAddr0( aGroupName, aTraceName, aParam )

   444 

   445 #endif // BLUETOOTHTRACE_ENABLED

   446 

   447 /*

   448  * Additional general purpose definition, a hook for defining a friend class

   449  * for unit testing to get access to class internals.

   450  */

   451 #ifndef BTUNITTEST

   452 #define BTUNITTESTHOOK

   453 #endif

   454 

   455 #endif // BLUETOOTHTRACE_H