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.
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:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
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.
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
38 * Declaration of functions for reporting debug output.
44 #include <complib/cl_debug_osd.h>
47 # define BEGIN_C_DECLS extern "C" {
48 # define END_C_DECLS }
49 #else /* !__cplusplus */
50 # define BEGIN_C_DECLS
52 #endif /* __cplusplus */
55 /****h* Component Library/Debug Output
60 * The debug output functions and macros send debug messages to the current
63 /****f* Component Library: Debug Output/cl_break
68 * The cl_break function halts execution.
75 * This function does not return a value.
78 * In a release build, cl_break has no effect.
80 /****f* Component Library: Debug Output/cl_is_debug
85 * The cl_is_debug function returns TRUE if the complib was compiled
86 * in debug mode, and FALSE otherwise.
90 boolean_t cl_is_debug(void);
96 * TRUE if compiled in debug version. FALSE otherwise.
102 #if defined( _DEBUG_ )
104 /****f* Component Library: Debug Output/cl_dbg_out
109 * The cl_dbg_out function sends a debug message to the debug target in
114 void cl_dbg_out(IN const char *const debug_message, IN ...);
118 * [in] ANSI string formatted identically as for a call to the standard C
122 * [in] Extra parameters for string formatting, as defined for the
123 * standard C function printf.
126 * This function does not return a value.
129 * In a release build, cl_dbg_out has no effect.
131 * The formatting of the debug_message string is the same as for printf
133 * cl_dbg_out sends the debug message to the current debug target.
136 * Debug Output, cl_msg_out
140 static inline void cl_dbg_out(IN const char *const debug_message, IN ...)
142 UNUSED_PARAM(debug_message);
144 #endif /* defined( _DEBUG_ ) */
147 /****f* Component Library: Debug Output/cl_msg_out
152 * The cl_msg_out function sends a debug message to the message log target.
156 void cl_msg_out(IN const char *const message, IN ...);
160 * [in] ANSI string formatted identically as for a call to the standard C
164 * [in] Extra parameters for string formatting, as defined for the
165 * standard C function printf.
168 * This function does not return a value.
171 * cl_msg_out is available in both debug and release builds.
173 * The formatting of the message string is the same as for printf
175 * cl_msg_out sends the message to the current message logging target.
178 * Debug Output, cl_dbg_out
182 /****d* Component Library: Debug Output/Debug Levels
187 * The debug output macros reserve the upper bit of the debug level to
192 #define CL_DBG_DISABLE 0
193 #define CL_DBG_ERROR 0x80000000
194 #define CL_DBG_ALL 0xFFFFFFFF
198 * Disable all debug output, including errors.
201 * Enable error debug output.
204 * Enbale all debug output.
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.
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.
216 * Debug Output, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE, CL_TRACE_EXIT
221 /****d* Component Library: Debug Output/CL_PRINT
226 * The CL_PRINT macro sends a string to the current debug target if
227 * the requested debug level matches the current debug level.
230 * CL_PRINT( DBG_LVL, CHK_LVL, STRING );
234 * [in] Debug level for the string to output
237 * [in] Current debug level against which to check DBG_LVL
240 * [in] String to send to the current debug target. The string includes
241 * parentheses in order to allow additional parameters.
244 * This macro does not return a value.
247 * #define MY_FUNC_DBG_LVL 1
249 * uint32_t my_dbg_lvl = CL_DBG_ALL;
254 * CL_PRINT( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") );
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.
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.
271 * Debug Output, Debug Levels, CL_ENTER, CL_EXIT, CL_TRACE, CL_TRACE_EXIT
273 #define CL_PRINT( DBG_LVL, CHK_LVL, STRING ) \
275 if( DBG_LVL & CL_DBG_ERROR ) \
277 else if( (DBG_LVL & CHK_LVL) == DBG_LVL ) \
281 /****d* Component Library: Debug Output/CL_ENTER
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.
291 * CL_ENTER( DBG_LVL, CHK_LVL );
295 * [in] Debug level for the string to output
298 * [in] Current debug level against which to check DBG_LVL
301 * This macro does not return a value.
304 * #define __MODULE__ "my_module"
305 * #define MY_FUNC_DBG_LVL 1
307 * uint32_t my_dbg_lvl = CL_DBG_ALL;
312 * CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl );
313 * CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl );
317 * my_module:my_func() [
318 * my_module:my_func() ]
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.
324 * If the __MODULE__ preprocessor keyword is defined, that keyword will be
325 * prepended to the function name, separated with a colon.
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.
332 * Debug Output, Debug Levels, CL_PRINT, CL_EXIT, CL_TRACE, CL_TRACE_EXIT
334 #define CL_ENTER( DBG_LVL, CHK_LVL ) \
336 CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_ENTER );
338 /****d* Component Library: Debug Output/CL_EXIT
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.
348 * CL_EXIT( DBG_LVL, CHK_LVL );
352 * [in] Debug level for the string to output
355 * [in] Current debug level against which to check DBG_LVL
358 * This macro does not return a value.
361 * #define __MODULE__ "my_module"
362 * #define MY_FUNC_DBG_LVL 1
364 * uint32_t my_dbg_lvl = CL_DBG_ALL;
369 * CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl );
370 * CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl );
374 * my_module:my_func() [
375 * my_module:my_func() ]
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.
381 * The CL_EXIT macro must only be used after the CL_ENTRY macro as it
382 * depends on that macro's implementation.
384 * If the __MODULE__ preprocessor keyword is defined, that keyword will be
385 * prepended to the function name, separated with a colon.
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.
392 * Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_TRACE, CL_TRACE_EXIT
394 #define CL_EXIT( DBG_LVL, CHK_LVL ) \
395 CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_EXIT );
397 /****d* Component Library: Debug Output/CL_TRACE
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.
408 * CL_TRACE( DBG_LVL, CHK_LVL, STRING );
412 * [in] Debug level for the string to output
415 * [in] Current debug level against which to check DBG_LVL
418 * [in] String to send to the current debug target. The string includes
419 * parentheses in order to allow additional parameters.
422 * This macro does not return a value.
425 * #define __MODULE__ "my_module"
426 * #define MY_FUNC_DBG_LVL 1
428 * uint32_t my_dbg_lvl = CL_DBG_ALL;
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 );
439 * my_module:my_func() [
440 * my_module:my_func(): Hello world!
441 * my_module:my_func() ]
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.
447 * The CL_TRACE macro must only be used after the CL_ENTRY macro as it
448 * depends on that macro's implementation.
450 * If the DBG_LVL has the upper bit set, the output will contain
451 * an "!ERROR!" statement between the function name and STRING.
453 * If the __MODULE__ preprocessor keyword is defined, that keyword will be
454 * prepended to the function name, separated with a colon.
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.
461 * Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE_EXIT
463 #define CL_TRACE( DBG_LVL, CHK_LVL, STRING ) \
465 switch( DBG_LVL & CL_DBG_ERROR ) \
468 CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_ERROR ); \
471 CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_INFO ); \
474 CL_PRINT( DBG_LVL, CHK_LVL, STRING ); \
477 /****d* Component Library: Debug Output/CL_TRACE_EXIT
482 * The CL_TRACE_EXIT macro combines the functionality of the CL_TRACE and
483 * CL_EXIT macros, in that order.
486 * CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING );
490 * [in] Debug level for the string to output
493 * [in] Current debug level against which to check DBG_LVL
496 * [in] String to send to the current debug target. The string includes
497 * parentheses in order to allow additional parameters.
500 * This macro does not return a value.
503 * #define __MODULE__ "my_module"
504 * #define MY_FUNC_DBG_LVL 1
506 * uint32_t my_dbg_lvl = CL_DBG_ALL;
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") );
516 * my_module:my_func() [
517 * my_module:my_func(): Hello world!
518 * my_module:my_func() ]
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.
524 * The CL_TRACE_EXIT macro must only be used after the CL_ENTRY macro as it
525 * depends on that macro's implementation.
527 * If the DBG_LVL has the upper bit set, the output will contain
528 * an "!ERROR!" statement between the function name and STRING.
530 * If the __MODULE__ preprocessor keyword is defined, that keyword will be
531 * prepended to the function name, separated with a colon.
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.
538 * Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE
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 );
544 #else /* defined(_DEBUG_) */
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 );
553 #endif /* defined(_DEBUG_) */
555 /****d* Component Library: Debug Output/64-bit Print Format
557 * 64-bit Print Format
560 * The 64-bit print keywords allow users to use 64-bit values in debug or
563 * Different platforms define 64-bit print formats differently. The 64-bit
564 * print formats exposed by the component library are supported in all
569 * Print a 64-bit integer in signed decimal format.
571 * Print a 64-bit integer in hexadecimal format.
573 * Print a 64-bit integer in octal format.
575 * Print a 64-bit integer in unsigned decimal format.
579 * // Print a 64-bit integer in hexadecimal format.
580 * cl_dbg_out( "MyVal: 0x%" PRIx64 "\n", MyVal );
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.
586 * The above keywords are strings and make use of compilers' string
587 * concatenation ability.
589 void complib_init(void);
591 void complib_exit(void);
594 #endif /* _CL_DEBUG_H_ */