1 /*

     2 * Copyright (c) 2006-2008 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:  Logging macros

    15 *

    16 */

    17 

    18 

    19 #ifndef MULLOG_H

    20 #define MULLOG_H

    21 

    22 //  log on debug builds because of performance

    23 #ifdef _DEBUG

    24 #define MUL_LOGGING_ENABLED

    25 #endif

    26 

    27 #ifndef MUL_LOGGING_ENABLED

    28 

    29     // empty declarations to clean up code

    30     #define MUL_LOG_ENTRY_EXIT( s )

    31     #define MUL_LOG_ENTRY_EXIT_LEAVE_L( s )

    32     #define MUL_LOG_INFO( s )

    33     #define MUL_LOG_INFO1( s, i )

    34     #define MUL_LOG_INFO2( s, i, j )

    35     #define MUL_LOG_INFO3( s, i, j, k )

    36     #define MUL_LOG_INFO4( s, i, j, k, l )

    37     #define MUL_LOG_INFO5( s, i, j, k, l, m )

    38     #define MUL_LOG_WARNING( s )

    39     #define MUL_LOG_WARNING1( s, i )

    40     #define MUL_LOG_WARNING2( s, i, j )

    41     #define MUL_LOG_WARNING3( s, i, j, k )

    42     #define MUL_LOG_ERROR( s )

    43     #define MUL_LOG_ERROR1( s, i )

    44     #define MUL_LOG_ERROR2( s, i, j )

    45     #define MUL_LOG_ERROR3( s, i, j, k )

    46     #define MUL_FUNC( s )

    47     #define MUL_FUNCL( s )

    48     #define MUL_DEBUG1( s )

    49     #define MUL_DEBUG2( s, i )

    50     #define MUL_DEBUG3( s, i, j )

    51     #define MUL_DEBUG4( s, i, j, k )

    52     #define MUL_DEBUG5( s, i, j, k, l )

    53 

    54 #else

    55 

    56 // only include headers if logging is enabled

    57 #include <e32std.h>

    58 #include <e32base.h>

    59 #include "mullogger.h"

    60 

    61 

    62     /**

    63      * Helper macro for defining debug string with filename

    64      * Note! this is internal so dont use outside this header

    65      */

    66     #ifdef __arm__

    67         // use the module name instead as its the filename without path

    68         #define MUL_DEBUG_STR( cat, str ) __MODULE__ "(%d) : " ##cat " : " ##str

    69     #else

    70         // put full file paths off for __FILE__ macro to make the log entries shorter

    71         #pragma fullpath_file off

    72         #define MUL_DEBUG_STR( cat, str ) __FILE__ "(%d) : " ##cat " : " ##str

    73     #endif

    74 

    75     /**

    76      * Helper macro for defining debug string with filename and linenumber

    77      * @param category the category string for the log entry

    78      * @param string the string for the log entry

    79      * Note! this is internal so dont use outside this header

    80      */

    81     #define MUL_DEBUG_LINE( category, string ) \

    82         TPtrC8((const TText8*) MUL_DEBUG_STR( category, string ) ), __LINE__

    83 

    84     /**

    85      * Output to mul logger

    86      * Note! this is internal so dont use outside this header

    87      */

    88     #define MUL_DEBUG_PRINT MulLogger::WriteFormat

    89 

    90     // LOGGING MACROS

    91     /**

    92      * Logs the entry and exit point of the function

    93      * Does not log the filename nor linenumber as inlining does not work

    94      * if you want to log the filename and linenumber, 

    95      * use MUL_LOG_INFO macros instead

    96      * Example usage:

    97      * 	MUL_LOG_ENTRY_EXIT( "CFoo::Bar()" );

    98      * @param a string to be added to the log

    99      */

   100     #define MUL_LOG_ENTRY_EXIT( s ) TMulFunctionTrace _tracer( _L8( s ) )

   101 

   102     /**

   103      * Logs the entry, exit and possible leave point of the function.

   104      * Note! cannot be used in a non leaving function or inside a LC function 

   105      * as this macro uses the cleanup stack

   106      * Does not log the filename nor linenumber as inlining does not work

   107      * if you want to log the filename and linenumber, 

   108      * use MUL_LOG_INFO macros instead

   109      * Example usage:

   110      * 	MUL_LOG_ENTRY_EXIT_LEAVE_L( "CFoo::Bar()" );

   111      * @param a string to be added to the log

   112      * @deprecated use MUL_LOG_ENTRY_EXIT instead as it also detects leave and does not require cleanupstack to work

   113      */

   114     #define MUL_LOG_ENTRY_EXIT_LEAVE_L( s ) \

   115         TMulFunctionTraceWithLeaveDetection _tracer( _L8( s ) ); \

   116         CleanupClosePushL( _tracer )

   117 

   118     /**

   119      * Logs a single line of information and the filename and linenumber

   120      * Example usage:

   121      * 	MUL_LOG_INFO( "CFoo::Bar()" );

   122      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   123      */

   124     #define MUL_LOG_INFO( s ) \

   125         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "info", s ) )

   126 

   127     /**

   128      * Logs a single line of information with one parameter 

   129      * and the filename and linenumber

   130       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   131       * values.

   132      * For the parameter string, use %d for int, %f for float and %S for address of descriptor

   133      * Example usage:

   134      * 	MUL_LOG_INFO1( "CFoo::Bar(%d)", aInt );

   135      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   136      * @param i, value to be inserted to the string, can be of any type

   137      */

   138     #define MUL_LOG_INFO1( s, i ) \

   139         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "info", s ), i )

   140 

   141     /**

   142      * Logs a single line of information with two parameters

   143      * along with the filename and linenumber

   144      * For the parameter string, use %d for int, %f for float and %S for address of descriptor

   145       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   146       * values.

   147      * Example usage:

   148      * 	MUL_LOG_INFO2( "CFoo::Bar(%d,%f)", aInt, aFloat );

   149      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   150      * @param i, value to be inserted to the string, can be of any type

   151      * @param j, value to be inserted to the string, can be of any type

   152      */

   153     #define MUL_LOG_INFO2( s, i, j ) \

   154         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "info", s ), i, j )

   155 

   156     /**

   157      * Logs a single line of information with three parameters

   158      * along with the filename and linenumber

   159      * For the parameter string, use %d for int, %f for float and %S for address of descriptor

   160       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   161       * values.

   162      * Example usage:

   163      * 	MUL_LOG_INFO3( "CFoo::Bar(%d,%S,%f)", aInt, &aDesC, aFloat );

   164      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   165      * @param i, value to be inserted to the string, can be of any type

   166      * @param j, value to be inserted to the string, can be of any type

   167      * @param k, value to be inserted to the string, can be of any type

   168      */

   169     #define MUL_LOG_INFO3( s, i, j, k ) \

   170         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "info", s ), i, j, k )

   171 

   172     /**

   173      * Logs a single line of information with four parameters

   174      * along with the filename and linenumber

   175      * For the parameter string, use %d for int, %f for float and %S for address of descriptor

   176       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   177       * values.

   178      * Example usage:

   179      * 	MUL_LOG_INFO4( "CFoo::Bar(%d,%f,%S,%s)", aInt, aFloat, "string" );

   180      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   181      * @param i, value to be inserted to the string, can be of any type

   182      * @param j, value to be inserted to the string, can be of any type

   183      * @param k, value to be inserted to the string, can be of any type

   184      * @param l, value to be inserted to the string, can be of any type

   185      */

   186     #define MUL_LOG_INFO4( s, i, j, k, l ) \

   187         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "info", s ), i, j, k, l )

   188 

   189     /**

   190      * Logs a single line of information with five parameters

   191      * along with the filename and linenumber

   192      * For the parameter string, use %d for int, %f for float and %S for address of descriptor

   193       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   194       * values.

   195      * Example usage:

   196      * 	MUL_LOG_INFO5( 

   197      *       "CFoo::Bar(%.1f,%.2f,%.3f,%.4f,%.5f)", aFloat1, aFloat2, aFloat3, aFloat4, aFloat5 );

   198      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   199      * @param i, value to be inserted to the string, can be of any type

   200      * @param j, value to be inserted to the string, can be of any type

   201      * @param k, value to be inserted to the string, can be of any type

   202      * @param l, value to be inserted to the string, can be of any type

   203      * @param m, value to be inserted to the string, can be of any type

   204      */

   205     #define MUL_LOG_INFO5( s, i, j, k, l, m ) \

   206         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "info", s ), i, j, k, l, m )

   207 

   208     /**

   209      * Logs a single line of warning and the filename and linenumber

   210      * Example usage:

   211      * 	MUL_LOG_WARNING( "Incorrect state, resetting state" );

   212      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   213      */

   214     #define MUL_LOG_WARNING( s ) \

   215         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "warning", s ) )

   216 

   217     /**

   218      * Logs a single line of warning with one parameter 

   219      * and the filename and linenumber

   220      * For the parameter string, use %d for int, %f for float and %S for address of descriptor

   221       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   222       * values.

   223      * Example usage:

   224      *  MUL_LOG_WARNING1( "Incorrect parameter %d", aInt );

   225      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   226      * @param i, value to be inserted to the string, can be of any type

   227      */

   228     #define MUL_LOG_WARNING1( s, i ) \

   229         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "warning", s ), i )

   230 

   231     /**

   232      * Logs a single line of warning with two parameters

   233      * along with the filename and linenumber

   234      * For the parameter string, use %d for int, %f for float and %S for address of descriptor

   235       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   236       * values.

   237      * Example usage:

   238      *  MUL_LOG_WARNING2( "Incorrect parameter %f, defaulting to %f", aInputFloat, KDefaultFloat );

   239      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   240      * @param i, value to be inserted to the string, can be of any type

   241      * @param j, value to be inserted to the string, can be of any type

   242      */

   243     #define MUL_LOG_WARNING2( s, i, j ) \

   244         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "warning", s ), i , j )

   245 

   246     /**

   247      * Logs a single line of warning with three parameters

   248      * along with the filename and linenumber

   249      * For the parameter string, use %d for int, %f for float and %S for address of descriptor

   250       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   251       * values.

   252      * Example usage:

   253      *  MUL_LOG_WARNING3( "Incorrect size (%d,%d), scale is %f", aWidth, aHeight, aScale );

   254      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   255      * @param i, value to be inserted to the string, can be of any type

   256      * @param j, value to be inserted to the string, can be of any type

   257      * @param k, value to be inserted to the string, can be of any type

   258      */

   259     #define MUL_LOG_WARNING3( s, i, j, k ) \

   260         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "warning", s ), i, j, k )

   261 

   262     /**

   263      * Logs a single line of error and the filename and linenumber.

   264      * Use this macro to track your asserts and panics so you can see them in the log and 

   265      * have a trace to come back to later on.

   266       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   267       * values.

   268      * Example usage:

   269      *  MUL_LOG_ERROR( "Incorrect state, going to panic" );

   270      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   271      */

   272     #define MUL_LOG_ERROR( s ) MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "error", s ) )

   273 

   274     /**

   275      * Logs a single line of error with one parameter and the filename and linenumber

   276      * Use this macro to track your asserts and panics so you can see them in the log and 

   277      * have a trace to come back to later on.

   278      * For the parameter string, use %d for int, %f for float and %S for address of descriptor

   279       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   280       * values.

   281      * Example usage:

   282      *  MUL_LOG_ERROR1( "Incorrect parameter %d, panicing", aInt );

   283      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   284      * @param i, value to be inserted to the string, can be of any type

   285      */

   286     #define MUL_LOG_ERROR1( s, i ) \

   287         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "error", s ), i )

   288 

   289     /**

   290      * Logs a single line of error with one parameter and the filename and linenumber

   291      * Use this macro to track your asserts and panics so you can see them in the log and 

   292      * have a trace to come back to later on.

   293      * For the parameter string, use %d for int, %f for float and %S for address of descriptor

   294       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   295       * values.

   296      * Example usage:

   297      *  MUL_LOG_ERROR2( "Incorrect size (%d,%d), panicking", aWidth, aHeight );

   298      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   299      * @param i, value to be inserted to the string, can be of any type

   300      * @param j, value to be inserted to the string, can be of any type

   301      */

   302     #define MUL_LOG_ERROR2( s, i, j ) \

   303         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "error", s ), i, j )

   304 

   305     /**

   306      * Logs a single line of error with one parameter and the filename and linenumber

   307      * Use this macro to track your asserts and panics so you can see them in the log and 

   308      * have a trace to come back to later on.

   309      * For the parameter string, use %d for int, %f for float and %S for address of descriptor

   310       * NOTE! logging is done in 8 bit strings so you cannot format 16 bit descriptor

   311       * values.

   312      * Example usage:

   313      *  MUL_LOG_ERROR3( "Incorrect state %d,%d,%f, panicking", aInt, aInt2, aFloat );

   314      * @param s, the string to be inserted to the log, plain compile time string, not a descriptor

   315      * @param i, value to be inserted to the string, can be of any type

   316      * @param j, value to be inserted to the string, can be of any type

   317      * @param k, value to be inserted to the string, can be of any type

   318      */

   319     #define MUL_LOG_ERROR3( s, i, j, k ) \

   320         MUL_DEBUG_PRINT( MUL_DEBUG_LINE( "error", s ), i, j, k )

   321 

   322     // Old macros for compatibility 

   323     ///@deprecated, use MUL_LOG_ENTRY_EXIT instead

   324     #define MUL_FUNC( s ) MUL_LOG_ENTRY_EXIT( s )

   325     ///@deprecated, use MUL_LOG_ENTRY_EXIT_LEAVE_L instead

   326     #define MUL_FUNCL( s )	MUL_LOG_ENTRY_EXIT_LEAVE_L( s )

   327     ///@deprecated, use MUL_LOG_INFO instead

   328     #define MUL_DEBUG1( s ) MUL_LOG_INFO( s )

   329     ///@deprecated, use MUL_LOG_INFO1 instead

   330     #define MUL_DEBUG2( s, i ) MUL_LOG_INFO1( s, i )

   331     ///@deprecated, use MUL_LOG_INFO2 instead

   332     #define MUL_DEBUG3( s, i, j ) MUL_LOG_INFO2( s, i, j )

   333     ///@deprecated, use MUL_LOG_INFO3 instead

   334     #define MUL_DEBUG4( s, i, j, k ) MUL_LOG_INFO3( s, i, j, k )

   335     ///@deprecated, use MUL_LOG_INFO4 instead

   336     #define MUL_DEBUG5( s, i, j, k, l ) MUL_LOG_INFO4( s, i, j, k, l )

   337 

   338     /**

   339      * TRAP instrumentation for Leave

   340      */

   341     #undef TRAP_INSTRUMENTATION_LEAVE

   342     #define TRAP_INSTRUMENTATION_LEAVE( aResult ) \

   343         MUL_LOG_INFO1( "Leave %d TRAPPED", aResult )

   344 

   345     /**

   346      * Helper class to track function entry and exit.

   347      */

   348     class TMulFunctionTrace

   349         {

   350         public:

   351             inline TMulFunctionTrace( TRefByValue< const TDesC8 > aName )

   352                 : iStr( aName )

   353                 {

   354                 // not using MUL_DEBUG2 as this function does not inline

   355                 MUL_DEBUG_PRINT( _L8( "Entry : %S" ), &iStr );

   356                 }

   357             inline ~TMulFunctionTrace()

   358                 {

   359                 if( std::uncaught_exception() )

   360                     {

   361                     // not using MUL_DEBUG2 as this function does not inline

   362                     MUL_DEBUG_PRINT( _L8( "Leave: %S" ), &iStr );

   363                     }

   364                 else

   365                     {

   366                     // not using MUL_DEBUG2 as this function does not inline

   367                     MUL_DEBUG_PRINT( _L8( "Exit : %S" ), &iStr );

   368                     }

   369                 }

   370         private:

   371             TPtrC8 iStr;

   372         };

   373 

   374     /**

   375      * Helper class to track function entry, exit and possible leave.

   376      * Never instantiate this class by itself.

   377      * Only ever user the macro MUL_FUNCL as this calls CleanupClosePushL

   378      * If you don't use the macro the destructor will panic in CleanupStack::Pop( this )

   379      * DO NOT use this in a LC method such as NewLC. 

   380      * Cleanup stack will be popped in the wrong order causing unwanted behaviour

   381      */

   382     class TMulFunctionTraceWithLeaveDetection

   383         {

   384         public:

   385             inline TMulFunctionTraceWithLeaveDetection( TRefByValue<const TDesC8> aName )

   386                 : iStr( aName ), iLeave( EFalse )

   387                 {

   388                 // not using MUL_DEBUG2 as this function does not inline

   389                 MUL_DEBUG_PRINT( _L8( "Entry : %S" ), &iStr );

   390                 }

   391             inline ~TMulFunctionTraceWithLeaveDetection()

   392                 {

   393                 // Did we leave

   394                 if( iLeave )                         

   395                     {

   396                     // not using MUL_DEBUG2 as this function does not inline

   397                     MUL_DEBUG_PRINT( _L8( "Leave : %S" ), &iStr );

   398                     }

   399                 else

   400                     {

   401                     // not using MUL_DEBUG2 as this function does not inline

   402                     MUL_DEBUG_PRINT( _L8( "Exit : %S" ), &iStr );

   403                     // Remove this from Cleanup. 

   404                     CleanupStack::Pop( this );

   405                     }

   406                 }

   407             void Close() // This is only called if a leave happens.

   408                 {

   409                 iLeave = ETrue;

   410                 }

   411         private:

   412             TPtrC8 iStr;

   413             TBool iLeave;

   414         };

   415 

   416 #endif  // MULLOG_H

   417 

   418 #endif  // 

   419 // End of File