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