1 /*

     2  * Copyright (c) 2010 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  *   

    16  */

    17 

    18 #ifndef BLUETOOTHTRACE_H

    19 #define BLUETOOTHTRACE_H

    20 

    21 #include <e32base.h>

    22 #include "traceconfig.h"

    23 

    24 /*

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

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

    27  * each individual project.

    28  * 

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

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

    31  * 

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

    33  * its own space.

    34  * 

    35  */

    36 

    37 #ifdef BLUETOOTHTRACE_ENABLED

    38 

    39 #ifdef BLUETOOTHTRACE_MEDIA_OST

    40 

    41 /**

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

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

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

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

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

    47  */

    48 #include <OpenSystemTrace.h>

    49 

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

    51     OstTrace0( aGroupName, aTraceName, aTraceText )

    52 

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

    54     OstTrace1( aGroupName, aTraceName, aTraceText, aParam )

    55 

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

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

    58 

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

    60     OstTraceExt1( aGroupName, aTraceName, aTraceText, aParam )

    61 

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

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

    64 

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

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

    67 

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

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

    70 

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

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

    73 

    74 #define BOstraceFunctionEntry0( aTraceName ) \

    75     OstTraceFunctionEntry0( aTraceName )

    76 

    77 #define BOstraceFunctionEntry1( aTraceName, aInstance ) \

    78     OstTraceFunctionEntry1( aTraceName, aInstance )

    79 

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

    81     OstTraceFunctionEntryExt(aTraceName, aInstance, aArg)

    82 

    83 #define BOstraceFunctionExit0( aTraceName ) \ 

    84     OstTraceFunctionExit0( aTraceName )

    85 

    86 #define BOstraceFunctionExit1( aTraceName, aInstance ) \

    87     OstTraceFunctionExit1( aTraceName, aInstance )

    88 

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

    90     OstTraceFunctionExitExt(aTraceName, aInstance, aRetval)

    91     

    92 #define BOstraceEventStart0( aTraceName, aEventName ) \

    93     OstTraceEventStart0( aTraceName, aEventName )

    94     

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

    96     OstTraceEventStart1( aTraceName, aEventName, aParam )

    97 

    98 #define BOstraceEventStop( aTraceName, aEventName ) \

    99     OstTraceEventStop( aTraceName, aEventName )

   100 

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

   102     OstTraceState0( aTraceName, aStateName, aNewState )

   103 

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

   105     OstTraceState1( aTraceName, aStateName, aNewState, aInstance )

   106     

   107 #else  // BLUETOOTHTRACE_MEDIA_OST

   108 

   109 #ifdef BLUETOOTHTRACE_MEDIA_FILE

   110 #include <flogger.h>

   111 #else   

   112 #include <e32debug.h>

   113 #endif

   114 

   115 /**

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

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

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

   119  */

   120     

   121 /**

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

   123  * to trucate rather than panic the caller.

   124  */

   125 NONSHARABLE_CLASS( TBtTraceOflowTruncate8 ) : public TDes8Overflow

   126     {

   127 public:

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

   129     };

   130 

   131 NONSHARABLE_CLASS( TBtTraceOflowTruncate16 ) : public TDes16Overflow

   132     {

   133 public:

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

   135     };

   136 

   137 /**

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

   139  */

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

   141 {

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

   143     TBuf16<0x180> str; 

   144     TPtrC cp(KComponentName);

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

   146 #ifdef BLUETOOTHTRACE_MEDIA_FILE

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

   148 #else

   149     RDebug::Print( str );

   150 #endif

   151 }

   152 

   153 /*

   154  * trace with no parameters

   155  */

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

   157 {\

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

   159     Trace( TrGrp, TrTxt ); \

   160 }

   161 

   162 /*

   163  * trace with one 32-bit parameter

   164  */

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

   166 {\

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

   168     TBuf<512> buf; TBtTraceOflowTruncate16 overflow; \

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

   170     Trace( TrGrp, buf ); \

   171 }

   172 

   173 /*

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

   175  */

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

   177 

   178 /*

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

   180  */

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

   182     BOstrace1( aGroupName, aTraceName, aTraceText, aParam )

   183 

   184 /*

   185  * trace with two parameters.

   186  */

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

   188 {\

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

   190     TBuf<512> buf; TBtTraceOflowTruncate16 overflow; \

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

   192     Trace( TrGrp, buf ); \

   193 }

   194 

   195 /*

   196  * trace with three parameters.

   197  */

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

   199 {\

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

   201     TBuf<512> buf; TBtTraceOflowTruncate16 overflow; \

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

   203     Trace( TrGrp, buf ); \

   204 }

   205 

   206 /*

   207  * trace with four parameters

   208  */    

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

   210 {\

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

   212     TBuf<512> buf; TBtTraceOflowTruncate16 overflow; \

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

   214     Trace( TrGrp, buf ); \

   215 }

   216 

   217 /*

   218  * trace with five parameters

   219  */   

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

   221 {\

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

   223     TBuf<512> buf; TBtTraceOflowTruncate16 overflow; \

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

   225     Trace( TrGrp, buf ); \

   226 }

   227 

   228 /*

   229  * Function entry trace without extra parameters. 

   230  * The trace is mapped to TRACE_API group.

   231  */

   232 #define BOstraceFunctionEntry0( aTraceName ) \

   233 {\

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

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

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

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

   238     Trace( TrGrp, buf ); \

   239 }

   240 

   241 /*

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

   243  * "this" pointer.

   244  * The trace is mapped to TRACE_API group.

   245  */

   246 #define BOstraceFunctionEntry1( aTraceName, aInstance ) \

   247 {\

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

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

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

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

   252     TBtTraceOflowTruncate16 overflow; \

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

   254     Trace( TrGrp, buf ); \

   255 }

   256 

   257 /*

   258  * Function entry trace, which traces function parameters.

   259  * The trace is mapped to TRACE_API group. 

   260  */

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

   262 { \

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

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

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

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

   267     TBtTraceOflowTruncate16 overflow; \

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

   269     Trace( TrGrp, buf ); \

   270 }

   271 /*

   272  * Function exit trace without extra parameters. 

   273  * The trace is mapped to TRACE_API group.

   274  */

   275 #define BOstraceFunctionExit0( aTraceName ) \

   276 {\

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

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

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

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

   281     Trace( TrGrp, buf ); \

   282 }

   283 

   284 /*

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

   286  * for example "this" pointer.

   287  * The trace is mapped to TRACE_API group.

   288  */

   289 #define BOstraceFunctionExit1( aTraceName, aInstance ) \

   290 {\

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

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

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

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

   295     TBtTraceOflowTruncate16 overflow; \

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

   297     Trace( TrGrp, buf ); \

   298 }

   299 

   300 /*

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

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

   303  * The trace is mapped to TRACE_API group.

   304  */

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

   306 {\

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

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

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

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

   311     TBtTraceOflowTruncate16 overflow; \

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

   313     Trace( TrGrp, buf ); \

   314 }

   315 

   316 /*

   317  * Performance measurement event start trace without extra parameters. 

   318  * The trace is mapped to TRACE_PERFORMANCE group.

   319  */

   320 #define BOstraceEventStart0( aTraceName, aEventName ) \

   321 {\

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

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

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

   325     Trace( TrGrp, buf ); \

   326 }

   327 

   328 /*

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

   330  * The trace is mapped to TRACE_PERFORMANCE group.

   331  */

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

   333 {\

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

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

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

   337     TBtTraceOflowTruncate16 overflow; \

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

   339     Trace( TrGrp, buf ); \

   340 }

   341 

   342 /*

   343  * Performance measurement event end trace. 

   344  * The trace is mapped to TRACE_PERFORMANCE group.

   345  */

   346 #define BOstraceEventStop( aTraceName, aEventName ) \

   347 {\

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

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

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

   351     Trace( TrGrp, buf ); \

   352 }

   353 

   354 /*

   355  * State transition event.

   356  * The trace is mapped to TRACE_STATE group.

   357  */

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

   359 {\

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

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

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

   363     TBtTraceOflowTruncate16 overflow; \

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

   365     Trace( TrGrp, buf ); \

   366 }

   367 

   368 /*

   369  * State transition event with instance identifier.

   370  * The trace is mapped to TRACE_STATE group.

   371  */

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

   373 {\

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

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

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

   377     TBtTraceOflowTruncate16 overflow; \

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

   379     Trace( TrGrp, buf ); \

   380 }

   381 

   382 #endif // BLUETOOTHTRACE_MEDIA_OST

   383 

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

   385 

   386 /*

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

   388  */

   389 #define BtTraceBlock( exp ) {exp}

   390 

   391 /*

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

   393  * aParam must be TBTDevAddr type.

   394  */

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

   396 { \

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

   398     TBuf<12> buf; \

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

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

   401 }

   402 

   403 /*

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

   405  * aParam must be TBTDevAddr type.

   406  */

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

   408 { \

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

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

   411 }

   412 

   413 #else // BLUETOOTHTRACE_ENABLED

   414 

   415 #define BOstrace0( aGroupName, aTraceName, aTraceText )

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

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

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

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

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

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

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

   423 

   424 #define BOstraceFunctionEntry0( aTraceName )

   425 #define BOstraceFunctionEntry1( aTraceName, aInstance )

   426 #define BOstraceFunctionEntryExt(aTraceName, aInstance, aArg)

   427 #define BOstraceFunctionExit0( aTraceName )

   428 #define BOstraceFunctionExit1( aTraceName, aInstance )

   429 #define BOstraceEventStart0( aTraceName, aEventName )

   430 #define BOstraceEventStart1( aTraceName, aEventName, aParam )

   431 #define BOstraceFunctionExitExt(aTraceName, aInstance, aRetval)

   432 #define BOstraceEventStop( aTraceName, aEventName )

   433 #define BOstraceState0( aTraceName, aStateName, aNewState )

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

   435 

   436 #define BtTraceBlock( exp )

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

   438 #define BtTraceBtAddr0( aGroupName, aTraceName, aParam )

   439 

   440 #endif // BLUETOOTHTRACE_ENABLED

   441 

   442 /*

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

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

   445  */

   446 #ifndef BTUNITTEST

   447 #define BTUNITTESTHOOK

   448 #endif

   449 

   450 #endif // BLUETOOTHTRACE_H