1 /*

     2 * Copyright (c) 2002-2005 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 the License "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:  Contains methods for debug traces both in user space and kernel.

    15 *

    16 */

    17 

    18 

    19 #ifndef GENDEBUG_H

    20 #define GENDEBUG_H

    21 

    22 #ifndef __KERNEL_MODE__

    23 #include <e32svr.h>

    24 #endif // __KERNEL_MODE__

    25 

    26 /** @file gendebug.h

    27     @brief Common helper file for debugging. 

    28 

    29     The file contains methods for adding traces and hardcoded breakpoint.

    30 

    31     @page page1 A documentation for general helper module for doing debugging and tracing.

    32 

    33     @subsection subsec1 This subsection describes the usage of hardcoded breakpoints.

    34 

    35     Hardcoded breakpoints are usefull for allowing the execution to stop in right places

    36     without bringing the OS down like using general assertions would do. Hardcoded breakpoints

    37     must be used together with debugger. The hardcoded breakpoints are used by inserting

    38     macro _DBG_MUST_BREAK into source code.

    39 

    40     @note This feature has not been implemented yet.

    41 

    42     @subsection subsec2 This subsection describes the usage of trace utilities.

    43 

    44     Tracing is the most important way of doing HW level debugging (after looking the source of course).

    45     Most of times users don't have access to debuggers and doing debugging in the field can be greatly

    46     improved if there are great variety of configurable traces available.

    47 

    48     In order to use the macro in kernel space, ALWAYS_KERNEL must be defined in the MMP-file of the module.

    49 

    50     To use static tracing the module using these utilities must have defined DEBUG_LEVEL (this is integer constant) in

    51     MMP-file. This constant defines the bit-mask for the set of traces, which are put into code at the compile time. See

    52     the macro definitions for details.

    53 

    54     The other way to do tracing is to use run-time tracing, which requires from user to put class member variable iDbgLevel

    55     into their class. This variable is used the same way as the static flag by using bit-mask to define enabled traces. See

    56     the macro definitions for details.

    57 */

    58 

    59 #if defined(_DEBUG)

    60 #define _DBG_MUST_BREAK

    61 #else

    62 #define _DBG_MUST_BREAK

    63 #endif

    64 

    65 /**

    66  * Disable useless "macro 'xxxx' could become const variable" lint warnings.

    67  */

    68 //lint -save -e1923

    69 

    70 /** Critical trace-level is used when system is about to down very soon because of critical error. 

    71     In most cases this trace level can be replaced by using assert with trace but in some cases

    72     more information can be provided by using this debug level

    73 */

    74 #define CRIT_LEVEL              0x00000001

    75 

    76 /** Serious trace-level is used when something bad and unexpected has happened but system might be

    77     able to recover. In another words, software is not going to bring system forcefully down but

    78     that's exactly what might happen due to an error.

    79 */

    80 #define SERIOUS_LEVEL           0x00000002

    81 

    82 /* Error level is used to trace various errors, which are due to legal errors in normal operation. */

    83 #define ERROR_LEVEL             0x00000004

    84 

    85 /* Warning level is used to trace various warning, which are due to abnormal behaviour. */

    86 #define WARNING_LEVEL           0x00000008

    87 

    88 /* Info level is used to trace all general information. */

    89 #define INFO_LEVEL              0x00000010

    90 

    91 /* User definable trace level. This comment and definition should be replaced by the real usage. */

    92 #define USER_DEFINED_1          0x000010000

    93 /* User definable trace level. This comment and definition should be replaced by the real usage. */

    94 #define USER_DEFINED_2          0x000020000

    95 /* User definable trace level. This comment and definition should be replaced by the real usage. */

    96 #define USER_DEFINED_3          0x000040000

    97 /* User definable trace level. This comment and definition should be replaced by the real usage. */

    98 #define USER_DEFINED_4          0x000080000

    99 /* User definable trace level. This comment and definition should be replaced by the real usage. */

   100 #define USER_DEFINED_5          0x000100000

   101 /* User definable trace level. This comment and definition should be replaced by the real usage. */

   102 #define USER_DEFINED_6          0x000200000

   103 /* User definable trace level. This comment and definition should be replaced by the real usage. */

   104 #define USER_DEFINED_7          0x000400000

   105 /* User definable trace level. This comment and definition should be replaced by the real usage. */

   106 #define USER_DEFINED_8          0x000800000

   107 

   108 #define DEVICE_1_MASK           0x0000f000

   109 #define DEVICE_2_MASK           0x000f0000

   110 #define DEVICE_3_MASK           0x00f00000

   111 #define DEVICE_4_MASK           0x0f000000

   112 

   113 // Override debug-level definition for your own in MMP file

   114 #ifndef DEBUG_LEVEL

   115 #define DEBUG_LEVEL 0x000000FF

   116 #endif

   117 

   118 //lint -restore

   119 

   120 #pragma warning(disable : 4127)    // conditional expression is constant

   121 

   122 #if defined(_DEBUG) || defined(TRACES)

   123 

   124 // Do not directly use this macro

   125 //lint -emacro({717}, UtilDump)   do while(0)

   126 //lint -emacro({774}, UtilDump)   conditional expression is constant

   127 #define UtilDump(PFUNCTION,SRCLEVEL,TRGLEVEL,STRING) \

   128         do { \

   129             TUint32 _level = (TRGLEVEL); \

   130             if (SRCLEVEL & _level) { \

   131             PFUNCTION STRING; \

   132             } \

   133         } while (0)

   134 

   135 

   136 #if defined __MOMAP15XX__ || defined ALWAYS_KERNEL

   137 

   138 /** Macro for static tracing.

   139     The first parameters defines the trace level set where this trace belongs to

   140     and the second parameter contains the trace string used in ordinary RDebug::Print

   141     command. Example: 

   142     TraceDump(INFO_LEVEL,(_L("My %d trace",1)));

   143     */

   144 

   145 #define TraceDump(LEVEL,STRING) UtilDump(Kern::Printf,DEBUG_LEVEL,LEVEL,STRING)

   146 

   147 

   148 /** Macro for dynamic tracing.

   149     The first parameters defines the trace level set where this trace belongs to

   150     and the second parameter contains the trace string used in ordinary RDebug::Print

   151     command. Example: 

   152     TraceDump(INFO_LEVEL,(_L("My %d trace",1)));

   153     */

   154 

   155 #define RTraceDump(LEVEL,STRING) UtilDump(Kern::Printf,iDbgLevel,LEVEL,STRING)

   156 #else

   157 #define TraceDump(LEVEL,STRING) UtilDump(RDebug::Print,DEBUG_LEVEL,LEVEL,STRING)

   158 #define RTraceDump(LEVEL,STRING) UtilDump(RDebug::Print,iDbgLevel,LEVEL,STRING)

   159 #endif // __MOMAP15XX__ || ALWAYS_KERNEL

   160 

   161 #else

   162 //lint -emacro({717}, TraceDump) do while(0)

   163 #define TraceDump(LEVEL,STRING) do {} while (0)

   164 //lint -emacro({717}, RTraceDump) do while(0)

   165 #define RTraceDump(LEVEL,STRING) do {} while (0)

   166 #endif // _DEBUG

   167 

   168 #endif // GENDEBUG_H

   169 

   170 // End of file