|
1 /* |
|
2 * Copyright (c) 2002-2004 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: debug trace utility header |
|
15 * |
|
16 */ |
|
17 |
|
18 /* |
|
19 * %version: 3 % |
|
20 */ |
|
21 |
|
22 #ifndef GENDEBUG_H |
|
23 #define GENDEBUG_H |
|
24 |
|
25 #include <e32svr.h> |
|
26 |
|
27 /** @file gendebug.h |
|
28 @brief Common helper file for debugging. |
|
29 |
|
30 The file contains methods for adding traces and hardcoded breakpoint. |
|
31 |
|
32 @page page1 A documentation for general helper module for doing debugging and tracing. |
|
33 |
|
34 @subsection subsec1 This subsection describes the usage of hardcoded breakpoints. |
|
35 |
|
36 Hardcoded breakpoints are usefull for allowing the execution to stop in right places |
|
37 without bringing the OS down like using general assertions would do. Hardcoded breakpoints |
|
38 must be used together with debugger. The hardcoded breakpoints are used by inserting |
|
39 macro _DBG_MUST_BREAK into source code. |
|
40 |
|
41 @note This feature has not been implemented yet. |
|
42 |
|
43 @subsection subsec2 This subsection describes the usage of trace utilities. |
|
44 |
|
45 Tracing is the most important way of doing HW level debugging (after looking the source of course). |
|
46 Most of times users don't have access to debuggers and doing debugging in the field can be greatly |
|
47 improved if there are great variety of configurable traces available. |
|
48 |
|
49 In order to use the macro in kernel space, ALWAYS_KERNEL must be defined in the MMP-file of the module. |
|
50 |
|
51 To use static tracing the module using these utilities must have defined DEBUG_LEVEL (this is integer constant) in |
|
52 MMP-file. This constant defines the bit-mask for the set of traces, which are put into code at the compile time. See |
|
53 the macro definitions for details. |
|
54 |
|
55 The other way to do tracing is to use run-time tracing, which requires from user to put class member variable iDbgLevel |
|
56 into their class. This variable is used the same way as the static flag by using bit-mask to define enabled traces. See |
|
57 the macro definitions for details. |
|
58 */ |
|
59 |
|
60 #if defined(_DEBUG) |
|
61 #define _DBG_MUST_BREAK |
|
62 #else |
|
63 #define _DBG_MUST_BREAK |
|
64 #endif |
|
65 |
|
66 /** Critical trace-level is used when system is about to down very soon because of critical error. |
|
67 In most cases this trace level can be replaced by using assert with trace but in some cases |
|
68 more information can be provided by using this debug level |
|
69 */ |
|
70 #define CRIT_LEVEL 0x00000001 |
|
71 |
|
72 /** Serious trace-level is used when something bad and unexpected has happened but system might be |
|
73 able to recover. In another words, software is not going to bring system forcefully down but |
|
74 that's exactly what might happen due to an error. |
|
75 */ |
|
76 #define SERIOUS_LEVEL 0x00000002 |
|
77 |
|
78 /* Error level is used to trace various errors, which are due to legal errors in normal operation. */ |
|
79 #define ERROR_LEVEL 0x00000004 |
|
80 |
|
81 /* Warning level is used to trace various warning, which are due to abnormal behaviour. */ |
|
82 #define WARNING_LEVEL 0x00000008 |
|
83 |
|
84 /* Info level is used to trace all general information. */ |
|
85 #define INFO_LEVEL 0x00000010 |
|
86 |
|
87 /* User definable trace level. This comment and definition should be replaced by the real usage. */ |
|
88 #define USER_DEFINED_1 0x000010000 |
|
89 /* User definable trace level. This comment and definition should be replaced by the real usage. */ |
|
90 #define USER_DEFINED_2 0x000020000 |
|
91 /* User definable trace level. This comment and definition should be replaced by the real usage. */ |
|
92 #define USER_DEFINED_3 0x000040000 |
|
93 /* User definable trace level. This comment and definition should be replaced by the real usage. */ |
|
94 #define USER_DEFINED_4 0x000080000 |
|
95 /* User definable trace level. This comment and definition should be replaced by the real usage. */ |
|
96 #define USER_DEFINED_5 0x000100000 |
|
97 /* User definable trace level. This comment and definition should be replaced by the real usage. */ |
|
98 #define USER_DEFINED_6 0x000200000 |
|
99 /* User definable trace level. This comment and definition should be replaced by the real usage. */ |
|
100 #define USER_DEFINED_7 0x000400000 |
|
101 /* User definable trace level. This comment and definition should be replaced by the real usage. */ |
|
102 #define USER_DEFINED_8 0x000800000 |
|
103 |
|
104 #define DEVICE_1_MASK 0x0000f000 |
|
105 #define DEVICE_2_MASK 0x000f0000 |
|
106 #define DEVICE_3_MASK 0x00f00000 |
|
107 #define DEVICE_4_MASK 0x0f000000 |
|
108 |
|
109 // Override debug-level definition for your own in MMP file |
|
110 #ifndef DEBUG_LEVEL |
|
111 //#define DEBUG_LEVEL 0 |
|
112 #define DEBUG_LEVEL WARNING_LEVEL |
|
113 //#define DEBUG_LEVEL WARNING_LEVEL | ERROR_LEVEL |
|
114 #endif |
|
115 |
|
116 #pragma warning(disable : 4127) // conditional expression is constant |
|
117 |
|
118 #if defined(_DEBUG) || defined(TRACES) |
|
119 |
|
120 // Do not directly use this macro |
|
121 //lint -emacro({717}, UtilDump) do while(0) |
|
122 //lint -emacro({774}, UtilDump) conditional expression is constant |
|
123 #define UtilDump(PFUNCTION,SRCLEVEL,TRGLEVEL,STRING) \ |
|
124 do { \ |
|
125 TUint32 _level = (TRGLEVEL); \ |
|
126 if (SRCLEVEL & _level) { \ |
|
127 PFUNCTION STRING; \ |
|
128 } \ |
|
129 } while (0) |
|
130 |
|
131 |
|
132 #if defined __MOMAP15XX__ || defined ALWAYS_KERNEL |
|
133 |
|
134 /** Macro for static tracing. |
|
135 The first parameters defines the trace level set where this trace belongs to |
|
136 and the second parameter contains the trace string used in ordinary RDebug::Print |
|
137 command. Example: |
|
138 TraceDump(INFO_LEVEL,(_L("My %d trace",1))); |
|
139 */ |
|
140 |
|
141 #define TraceDump(LEVEL,STRING) UtilDump(Kern::Printf,DEBUG_LEVEL,LEVEL,STRING) |
|
142 |
|
143 |
|
144 /** Macro for dynamic tracing. |
|
145 The first parameters defines the trace level set where this trace belongs to |
|
146 and the second parameter contains the trace string used in ordinary RDebug::Print |
|
147 command. Example: |
|
148 TraceDump(INFO_LEVEL,(_L("My %d trace",1))); |
|
149 */ |
|
150 |
|
151 #define RTraceDump(LEVEL,STRING) UtilDump(Kern::Printf,iDbgLevel,LEVEL,STRING) |
|
152 #else |
|
153 #define TraceDump(LEVEL,STRING) UtilDump(RDebug::Print,DEBUG_LEVEL,LEVEL,STRING) |
|
154 #define RTraceDump(LEVEL,STRING) UtilDump(RDebug::Print,iDbgLevel,LEVEL,STRING) |
|
155 #endif // __MOMAP15XX__ || ALWAYS_KERNEL |
|
156 |
|
157 #else |
|
158 //lint -emacro({717}, TraceDump) do while(0) |
|
159 #define TraceDump(LEVEL,STRING) do {} while (0) |
|
160 //lint -emacro({717}, RTraceDump) do while(0) |
|
161 #define RTraceDump(LEVEL,STRING) do {} while (0) |
|
162 #endif // _DEBUG |
|
163 |
|
164 #endif // GENDEBUG_H |
|
165 |
|
166 // End of file |