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