[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_debug.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 /*\r
35  * Abstract:\r
36  *      Declaration of functions for reporting debug output.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_DEBUG_H_\r
44 #define _CL_DEBUG_H_\r
45 \r
46 \r
47 #include <complib/cl_debug_osd.h>\r
48 \r
49 \r
50 /****h* Component Library/Debug Output\r
51 * NAME\r
52 *       Debug Output\r
53 *\r
54 * DESCRIPTION\r
55 *       The debug output functions and macros send debug messages to the current\r
56 *       debug target.\r
57 *********/\r
58 \r
59 \r
60 /****f* Component Library: Debug Output/cl_break\r
61 * NAME\r
62 *       cl_break\r
63 *\r
64 * DESCRIPTION\r
65 *       The cl_break function halts execution.\r
66 *\r
67 * SYNOPSIS\r
68 *       void\r
69 *       cl_break();\r
70 *\r
71 * RETURN VALUE\r
72 *       This function does not return a value.\r
73 *\r
74 * NOTES\r
75 *       In a release build, cl_break has no effect.\r
76 *********/\r
77 \r
78 \r
79 #ifdef __cplusplus\r
80 extern "C"\r
81 {\r
82 #endif\r
83 \r
84 #ifndef cl_dbg_out\r
85 #if defined( _DEBUG_ )\r
86 /****f* Component Library: Debug Output/cl_dbg_out\r
87 * NAME\r
88 *       cl_dbg_out\r
89 *\r
90 * DESCRIPTION\r
91 *       The cl_dbg_out function sends a debug message to the debug target in\r
92 *       debug builds only.\r
93 *\r
94 * SYNOPSIS\r
95 */\r
96 CL_EXPORT void\r
97 cl_dbg_out(\r
98         IN      const char* const       debug_message,\r
99         IN      ... );\r
100 /*\r
101 * PARAMETERS\r
102 *       debug_message\r
103 *               [in] ANSI string formatted identically as for a call to the standard C\r
104 *               function printf.\r
105 *\r
106 *       ...\r
107 *               [in] Extra parameters for string formatting, as defined for the\r
108 *               standard C function printf.\r
109 *\r
110 * RETURN VALUE\r
111 *       This function does not return a value.\r
112 *\r
113 * NOTES\r
114 *       In a release build, cl_dbg_out has no effect.\r
115 *\r
116 *       The formatting of the debug_message string is the same as for printf\r
117 *\r
118 *       cl_dbg_out sends the debug message to the current debug target.\r
119 *\r
120 * SEE ALSO\r
121 *       Debug Output, cl_msg_out\r
122 *********/\r
123 #else\r
124 CL_INLINE void\r
125 cl_dbg_out(\r
126         IN      const char* const       debug_message,\r
127         IN      ... )\r
128 {\r
129         UNUSED_PARAM( debug_message );\r
130 }\r
131 #endif  /* defined( _DEBUG_ ) */\r
132 #endif  /* !defined( cl_dbg_out ) */\r
133 \r
134 #ifndef cl_msg_out\r
135 /****f* Component Library: Debug Output/cl_msg_out\r
136 * NAME\r
137 *       cl_msg_out\r
138 *\r
139 * DESCRIPTION\r
140 *       The cl_msg_out function sends a debug message to the message log target.\r
141 *\r
142 * SYNOPSIS\r
143 */\r
144 CL_EXPORT void\r
145 cl_msg_out(\r
146         IN      const char* const       message,\r
147         IN      ... );\r
148 /*\r
149 * PARAMETERS\r
150 *       message\r
151 *               [in] ANSI string formatted identically as for a call to the standard C\r
152 *               function printf.\r
153 *\r
154 *       ...\r
155 *               [in] Extra parameters for string formatting, as defined for the\r
156 *               standard C function printf.\r
157 *\r
158 * RETURN VALUE\r
159 *       This function does not return a value.\r
160 *\r
161 * NOTES\r
162 *       cl_msg_out is available in both debug and release builds.\r
163 *\r
164 *       The formatting of the message string is the same as for printf\r
165 *\r
166 *       cl_msg_out sends the message to the current message logging target.\r
167 *\r
168 * SEE ALSO\r
169 *       Debug Output, cl_dbg_out\r
170 *********/\r
171 #endif\r
172 \r
173 #ifdef __cplusplus\r
174 }       /* extern "C" */\r
175 #endif\r
176 \r
177 \r
178 /****d* Component Library: Debug Output/Debug Levels\r
179 * NAME\r
180 *       Debug Levels\r
181 *\r
182 * DESCRIPTION\r
183 *       The debug output macros reserve the upper bit of the debug level to\r
184 *       convey an error.\r
185 *\r
186 * SYNOPSIS\r
187 */\r
188 #define CL_DBG_DISABLE          0\r
189 #define CL_DBG_ERROR            0x80000000\r
190 #define CL_DBG_ALL                      0xFFFFFFFF\r
191 /*\r
192 * VALUES\r
193 *       CL_DBG_DISABLE\r
194 *               Disable all debug output, including errors.\r
195 *\r
196 *       CL_DBG_ERROR\r
197 *               Enable error debug output.\r
198 *\r
199 *       CL_DBG_ALL\r
200 *               Enbale all debug output.\r
201 *\r
202 * NOTES\r
203 *       Users can define custom debug levels using the lower 31 bits of their\r
204 *       debug level to control non-error debug output.  Error messages are\r
205 *       always displayed, regardless of the lower bit definition.\r
206 *\r
207 *       When specifying the debug output desired for non-error messages\r
208 *       (the CHK_LVL parameter in the debug output macros), users must define\r
209 *       all bits whose output they are interested in.\r
210 *\r
211 * SEE ALSO\r
212 *       Debug Output, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE, CL_TRACE_EXIT\r
213 *********/\r
214 \r
215 \r
216 #if defined(_DEBUG_)\r
217 \r
218 /****d* Component Library: Debug Output/CL_PRINT\r
219 * NAME\r
220 *       CL_PRINT\r
221 *\r
222 * DESCRIPTION\r
223 *       The CL_PRINT macro sends a string to the current debug target if\r
224 *       the requested debug level matches the current debug level.\r
225 *\r
226 * SYNOPSIS\r
227 *       CL_PRINT( DBG_LVL, CHK_LVL, STRING );\r
228 *\r
229 * PARAMETERS\r
230 *       DBG_LVL\r
231 *               [in] Debug level for the string to output\r
232 *\r
233 *       CHK_LVL\r
234 *               [in] Current debug level against which to check DBG_LVL\r
235 *\r
236 *       STRING\r
237 *               [in] String to send to the current debug target.  The string includes\r
238 *               parentheses in order to allow additional parameters.\r
239 *\r
240 * RETURN VALUE\r
241 *       This macro does not return a value.\r
242 *\r
243 * EXAMPLE\r
244 *       #define MY_FUNC_DBG_LVL 1\r
245 *\r
246 *       uint32_t        my_dbg_lvl = CL_DBG_ALL;\r
247 *\r
248 *       void\r
249 *       my_func()\r
250 *       {\r
251 *               CL_PRINT( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") );\r
252 *       }\r
253 *\r
254 * RESULT\r
255 *       Hello world!\r
256 *\r
257 * NOTES\r
258 *       The requested string is printed only if all bits set in DBG_LVL are also\r
259 *       set in CHK_LVL unless the most significant bit is set (indicating an\r
260 *       error), in which case the lower bits are ignored.  CHK_LVL may have\r
261 *       additional bits set.\r
262 *\r
263 *       In multi-processor environments where the current processor can be\r
264 *       determined, the zero-based number of the processor on which the output\r
265 *       is generated is prepended to the output.\r
266 *\r
267 * SEE ALSO\r
268 *       Debug Output, Debug Levels, CL_ENTER, CL_EXIT, CL_TRACE, CL_TRACE_EXIT\r
269 *********/\r
270 #define CL_PRINT( DBG_LVL, CHK_LVL, STRING )                                                            \\r
271         do{                                                                                                                                             \\r
272         if( DBG_LVL & CHK_LVL & CL_DBG_ERROR )                                                                  \\r
273                 cl_dbg_out STRING;                                                                                                      \\r
274         else if( (DBG_LVL & CHK_LVL) == DBG_LVL )                                                               \\r
275                 cl_dbg_out STRING;                                                                                                      \\r
276         } while(CHK_LVL^CHK_LVL)\r
277 \r
278 \r
279 /****d* Component Library: Debug Output/CL_ENTER\r
280 * NAME\r
281 *       CL_ENTER\r
282 *\r
283 * DESCRIPTION\r
284 *       The CL_ENTER macro marks the entrance into a function by sending a\r
285 *       string to the current debug target if the requested debug level matches\r
286 *       the current debug level.\r
287 *\r
288 * SYNOPSIS\r
289 *       CL_ENTER( DBG_LVL, CHK_LVL );\r
290 *\r
291 * PARAMETERS\r
292 *       DBG_LVL\r
293 *               [in] Debug level for the string to output\r
294 *\r
295 *       CHK_LVL\r
296 *               [in] Current debug level against which to check DBG_LVL\r
297 *\r
298 * RETURN VALUE\r
299 *       This macro does not return a value.\r
300 *\r
301 * EXAMPLE\r
302 *       #define __MODULE__      "my_module"\r
303 *       #define MY_FUNC_DBG_LVL 1\r
304 *\r
305 *       uint32_t        my_dbg_lvl = CL_DBG_ALL;\r
306 *\r
307 *       void\r
308 *       my_func()\r
309 *       {\r
310 *               CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl );\r
311 *               CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl );\r
312 *       }\r
313 *\r
314 * RESULT\r
315 *       my_module:my_func() [\r
316 *       my_module:my_func() ]\r
317 *\r
318 * NOTES\r
319 *       The function entrance notification is printed only if all bits set\r
320 *       in DBG_LVL are also set in CHK_LVL.  CHK_LVL may have additional bits set.\r
321 *\r
322 *       If the __MODULE__ preprocessor keyword is defined, that keyword will be\r
323 *       prepended to the function name, separated with a colon.\r
324 *\r
325 *       In multi-processor environments where the current processor can be\r
326 *       determined, the zero-based number of the processor on which the output\r
327 *       is generated is prepended to the output.\r
328 *\r
329 * SEE ALSO\r
330 *       Debug Output, Debug Levels, CL_PRINT, CL_EXIT, CL_TRACE, CL_TRACE_EXIT\r
331 *********/\r
332 #define CL_ENTER( DBG_LVL, CHK_LVL )                                                                            \\r
333         do{                                                                                                                                             \\r
334         CL_CHK_STK;                                                                                                                             \\r
335         CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_ENTER );                                                    \\r
336         } while(CHK_LVL^CHK_LVL)\r
337 \r
338 \r
339 /****d* Component Library: Debug Output/CL_EXIT\r
340 * NAME\r
341 *       CL_EXIT\r
342 *\r
343 * DESCRIPTION\r
344 *       The CL_EXIT macro marks the exit from a function by sending a string\r
345 *       to the current debug target if the requested debug level matches the\r
346 *       current debug level.\r
347 *\r
348 * SYNOPSIS\r
349 *       CL_EXIT( DBG_LVL, CHK_LVL );\r
350 *\r
351 * PARAMETERS\r
352 *       DBG_LVL\r
353 *               [in] Debug level for the string to output\r
354 *\r
355 *       CHK_LVL\r
356 *               [in] Current debug level against which to check DBG_LVL\r
357 *\r
358 * RETURN VALUE\r
359 *       This macro does not return a value.\r
360 *\r
361 * EXAMPLE\r
362 *       #define __MODULE__      "my_module"\r
363 *       #define MY_FUNC_DBG_LVL 1\r
364 *\r
365 *       uint32_t        my_dbg_lvl = CL_DBG_ALL;\r
366 *\r
367 *       void\r
368 *       my_func()\r
369 *       {\r
370 *               CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl );\r
371 *               CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl );\r
372 *       }\r
373 *\r
374 * RESULT\r
375 *       my_module:my_func() [\r
376 *       my_module:my_func() ]\r
377 *\r
378 * NOTES\r
379 *       The exit notification is printed only if all bits set in DBG_LVL are also\r
380 *       set in CHK_LVL.  CHK_LVL may have additional bits set.\r
381 *\r
382 *       The CL_EXIT macro must only be used after the CL_ENTRY macro as it\r
383 *       depends on that macro's implementation.\r
384 *\r
385 *       If the __MODULE__ preprocessor keyword is defined, that keyword will be\r
386 *       prepended to the function name, separated with a colon.\r
387 *\r
388 *       In multi-processor environments where the current processor can be\r
389 *       determined, the zero-based number of the processor on which the output\r
390 *       is generated is prepended to the output.\r
391 *\r
392 * SEE ALSO\r
393 *       Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_TRACE, CL_TRACE_EXIT\r
394 *********/\r
395 #define CL_EXIT( DBG_LVL, CHK_LVL )                                                                                     \\r
396         CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_EXIT )\r
397 \r
398 \r
399 /****d* Component Library: Debug Output/CL_TRACE\r
400 * NAME\r
401 *       CL_TRACE\r
402 *\r
403 * DESCRIPTION\r
404 *       The CL_TRACE macro sends a string to the current debug target if\r
405 *       the requested debug level matches the current debug level.  The\r
406 *       output is prepended with the function name and, depending on the\r
407 *       debug level requested, an indication of the severity of the message.\r
408 *\r
409 * SYNOPSIS\r
410 *       CL_TRACE( DBG_LVL, CHK_LVL, STRING );\r
411 *\r
412 * PARAMETERS\r
413 *       DBG_LVL\r
414 *               [in] Debug level for the string to output\r
415 *\r
416 *       CHK_LVL\r
417 *               [in] Current debug level against which to check DBG_LVL\r
418 *\r
419 *       STRING\r
420 *               [in] String to send to the current debug target.  The string includes\r
421 *               parentheses in order to allow additional parameters.\r
422 *\r
423 * RETURN VALUE\r
424 *       This macro does not return a value.\r
425 *\r
426 * EXAMPLE\r
427 *       #define __MODULE__      "my_module"\r
428 *       #define MY_FUNC_DBG_LVL 1\r
429 *\r
430 *       uint32_t        my_dbg_lvl = CL_DBG_ALL;\r
431 *\r
432 *       void\r
433 *       my_func()\r
434 *       {\r
435 *               CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl );\r
436 *               CL_TRACE( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") );\r
437 *               CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl );\r
438 *       }\r
439 *\r
440 * RESULT\r
441 *       my_module:my_func() [\r
442 *       my_module:my_func(): Hello world!\r
443 *       my_module:my_func() ]\r
444 *\r
445 * NOTES\r
446 *       The requested string is printed only if all bits set in DBG_LVL are also\r
447 *       set in CHK_LVL.  CHK_LVL may have additional bits set.\r
448 *\r
449 *       The CL_TRACE macro must only be used after the CL_ENTRY macro as it\r
450 *       depends on that macro's implementation.\r
451 *\r
452 *       If the DBG_LVL has the upper bit set, the output will contain\r
453 *       an "!ERROR!" statement between the function name and STRING.\r
454 *\r
455 *       If the __MODULE__ preprocessor keyword is defined, that keyword will be\r
456 *       prepended to the function name, separated with a colon.\r
457 *\r
458 *       In multi-processor environments where the current processor can be\r
459 *       determined, the zero-based number of the processor on which the output\r
460 *       is generated is prepended to the output.\r
461 *\r
462 * SEE ALSO\r
463 *       Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE_EXIT\r
464 *********/\r
465 #define CL_TRACE( DBG_LVL, CHK_LVL, STRING )                                                            \\r
466 __pragma(warning(suppress:6326))                                                                                        \\r
467 do{                                                                                                                                                     \\r
468 switch( DBG_LVL & CL_DBG_ERROR )                                                                                        \\r
469 {                                                                                                                                                       \\r
470         case CL_DBG_ERROR:                                                                                                              \\r
471                 CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_ERROR );                                            \\r
472                 break;                                                                                                                          \\r
473         default:                                                                                                                                \\r
474                 CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_INFO );                                                     \\r
475                 break;                                                                                                                          \\r
476 }                                                                                                                                                       \\r
477 CL_PRINT( DBG_LVL, CHK_LVL, STRING );                                                                           \\r
478 } while(CHK_LVL^CHK_LVL)\r
479 \r
480 \r
481 /****d* Component Library: Debug Output/CL_TRACE_EXIT\r
482 * NAME\r
483 *       CL_TRACE_EXIT\r
484 *\r
485 * DESCRIPTION\r
486 *       The CL_TRACE_EXIT macro combines the functionality of the CL_TRACE and\r
487 *       CL_EXIT macros, in that order.\r
488 *\r
489 * SYNOPSIS\r
490 *       CL_TRACE_EXIT(  DBG_LVL, CHK_LVL, STRING );\r
491 *\r
492 * PARAMETERS\r
493 *       DBG_LVL\r
494 *               [in] Debug level for the string to output\r
495 *\r
496 *       CHK_LVL\r
497 *               [in] Current debug level against which to check DBG_LVL\r
498 *\r
499 *       STRING\r
500 *               [in] String to send to the current debug target.  The string includes\r
501 *               parentheses in order to allow additional parameters.\r
502 *\r
503 * RETURN VALUE\r
504 *       This macro does not return a value.\r
505 *\r
506 * EXAMPLE\r
507 *       #define __MODULE__      "my_module"\r
508 *       #define MY_FUNC_DBG_LVL 1\r
509 *\r
510 *       uint32_t        my_dbg_lvl = CL_DBG_ALL;\r
511 *\r
512 *       void\r
513 *       my_func()\r
514 *       {\r
515 *               CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl );\r
516 *               CL_TRACE_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") );\r
517 *       }\r
518 *\r
519 * RESULT\r
520 *       my_module:my_func() [\r
521 *       my_module:my_func(): Hello world!\r
522 *       my_module:my_func() ]\r
523 *\r
524 * NOTES\r
525 *       The requested string is printed only if all bits set in DBG_LVL are also\r
526 *       set in CHK_LVL.  CHK_LVL may have additional bits set.\r
527 *\r
528 *       The CL_TRACE_EXIT macro must only be used after the CL_ENTRY macro as it\r
529 *       depends on that macro's implementation.\r
530 *\r
531 *       If the DBG_LVL has the upper bit set, the output will contain\r
532 *       an "!ERROR!" statement between the function name and STRING.\r
533 *\r
534 *       If the __MODULE__ preprocessor keyword is defined, that keyword will be\r
535 *       prepended to the function name, separated with a colon.\r
536 *\r
537 *       In multi-processor environments where the current processor can be\r
538 *       determined, the zero-based number of the processor on which the output\r
539 *       is generated is prepended to the output.\r
540 *\r
541 * SEE ALSO\r
542 *       Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE\r
543 *********/\r
544 #define CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING )                                                       \\r
545         __pragma(warning(suppress:6326)) \\r
546         do{                                                                                                                                             \\r
547         CL_TRACE( DBG_LVL, CHK_LVL, STRING );                                                                   \\r
548         CL_EXIT( DBG_LVL, CHK_LVL );                                                                                    \\r
549         } while(CHK_LVL^CHK_LVL)\r
550 \r
551 #else   /* defined(_DEBUG_) */\r
552 \r
553 /* Define as NULL macros in a free build. */\r
554 #define CL_PRINT( DBG_LVL, CHK_LVL, STRING )\r
555 #define CL_ENTER( DBG_LVL, CHK_LVL )\r
556 #define CL_EXIT( DBG_LVL, CHK_LVL )\r
557 #define CL_TRACE( DBG_LVL, CHK_LVL, STRING )\r
558 #define CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING )\r
559 \r
560 #endif  /* defined(_DEBUG_) */\r
561 \r
562 \r
563 /****d* Component Library: Debug Output/64-bit Print Format\r
564 * NAME\r
565 *       64-bit Print Format\r
566 *\r
567 * DESCRIPTION\r
568 *       The 64-bit print keywords allow users to use 64-bit values in debug or\r
569 *       console output.\r
570 *\r
571 *       Different platforms define 64-bit print formats differently. The 64-bit\r
572 *       print formats exposed by the component library are supported in all\r
573 *       platforms.\r
574 *\r
575 * VALUES\r
576 *       PRId64\r
577 *               Print a 64-bit integer in signed decimal format.\r
578 *       PRIx64\r
579 *               Print a 64-bit integer in hexadecimal format.\r
580 *       PRIo64\r
581 *               Print a 64-bit integer in octal format.\r
582 *       PRIu64\r
583 *               Print a 64-bit integer in unsigned decimal format.\r
584 *\r
585 * EXAMPLE\r
586 *       uint64 MyVal = 2;\r
587 *       // Print a 64-bit integer in hexadecimal format.\r
588 *       cl_dbg_out( "MyVal: 0x%" PRIx64 "\n", MyVal );\r
589 *\r
590 * NOTES\r
591 *       Standard print flags to specify padding and precision can still be used\r
592 *       following the '%' sign in the string preceding the 64-bit print keyword.\r
593 *\r
594 *       The above keywords are strings and make use of compilers' string\r
595 *       concatenation ability.\r
596 *********/\r
597 \r
598 \r
599 #endif /* _CL_DEBUG_H_ */\r