/*
* Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
* Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
* Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
*
* This software is available to you under a choice of one of two
* licenses. You may choose to be licensed under the terms of the GNU
* General Public License (GPL) Version 2, available from the file
* COPYING in the main directory of this source tree, or the
* OpenIB.org BSD license below:
*
* Redistribution and use in source and binary forms, with or
* without modification, are permitted provided that the following
* conditions are met:
*
* - Redistributions of source code must retain the above
* copyright notice, this list of conditions and the following
* disclaimer.
*
* - Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following
* disclaimer in the documentation and/or other materials
* provided with the distribution.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
*/
/*
* Abstract:
* Declaration of functions for reporting debug output.
*/
#ifndef _CL_DEBUG_H_
#define _CL_DEBUG_H_
#include <complib/cl_debug_osd.h>
#ifdef __cplusplus
# define BEGIN_C_DECLS extern "C" {
# define END_C_DECLS }
#else /* !__cplusplus */
# define BEGIN_C_DECLS
# define END_C_DECLS
#endif /* __cplusplus */
BEGIN_C_DECLS
/****h* Component Library/Debug Output
* NAME
* Debug Output
*
* DESCRIPTION
* The debug output functions and macros send debug messages to the current
* debug target.
*********/
/****f* Component Library: Debug Output/cl_break
* NAME
* cl_break
*
* DESCRIPTION
* The cl_break function halts execution.
*
* SYNOPSIS
* void
* cl_break();
*
* RETURN VALUE
* This function does not return a value.
*
* NOTES
* In a release build, cl_break has no effect.
*********/
/****f* Component Library: Debug Output/cl_is_debug
* NAME
* cl_is_debug
*
* DESCRIPTION
* The cl_is_debug function returns TRUE if the complib was compiled
* in debug mode, and FALSE otherwise.
*
* SYNOPSIS
*/
boolean_t cl_is_debug(void);
/*
* PARAMETERS
* None
*
* RETURN VALUE
* TRUE if compiled in debug version. FALSE otherwise.
*
* NOTES
*
*********/
#if defined( _DEBUG_ )
#ifndef cl_dbg_out
/****f* Component Library: Debug Output/cl_dbg_out
* NAME
* cl_dbg_out
*
* DESCRIPTION
* The cl_dbg_out function sends a debug message to the debug target in
* debug builds only.
*
* SYNOPSIS
*/
void cl_dbg_out(IN const char *const debug_message, IN ...);
/*
* PARAMETERS
* debug_message
* [in] ANSI string formatted identically as for a call to the standard C
* function printf.
*
* ...
* [in] Extra parameters for string formatting, as defined for the
* standard C function printf.
*
* RETURN VALUE
* This function does not return a value.
*
* NOTES
* In a release build, cl_dbg_out has no effect.
*
* The formatting of the debug_message string is the same as for printf
*
* cl_dbg_out sends the debug message to the current debug target.
*
* SEE ALSO
* Debug Output, cl_msg_out
*********/
#endif
#else
static inline void cl_dbg_out(IN const char *const debug_message, IN ...)
{
UNUSED_PARAM(debug_message);
}
#endif /* defined( _DEBUG_ ) */
#ifndef cl_msg_out
/****f* Component Library: Debug Output/cl_msg_out
* NAME
* cl_msg_out
*
* DESCRIPTION
* The cl_msg_out function sends a debug message to the message log target.
*
* SYNOPSIS
*/
void cl_msg_out(IN const char *const message, IN ...);
/*
* PARAMETERS
* message
* [in] ANSI string formatted identically as for a call to the standard C
* function printf.
*
* ...
* [in] Extra parameters for string formatting, as defined for the
* standard C function printf.
*
* RETURN VALUE
* This function does not return a value.
*
* NOTES
* cl_msg_out is available in both debug and release builds.
*
* The formatting of the message string is the same as for printf
*
* cl_msg_out sends the message to the current message logging target.
*
* SEE ALSO
* Debug Output, cl_dbg_out
*********/
#endif
/****d* Component Library: Debug Output/Debug Levels
* NAME
* Debug Levels
*
* DESCRIPTION
* The debug output macros reserve the upper bit of the debug level to
* convey an error.
*
* SYNOPSIS
*/
#define CL_DBG_DISABLE 0
#define CL_DBG_ERROR 0x80000000
#define CL_DBG_ALL 0xFFFFFFFF
/*
* VALUES
* CL_DBG_DISABLE
* Disable all debug output, including errors.
*
* CL_DBG_ERROR
* Enable error debug output.
*
* CL_DBG_ALL
* Enbale all debug output.
*
* NOTES
* Users can define custom debug levels using the lower 31 bits of their
* debug level to control non-error debug output. Error messages are
* always displayed, regardless of the lower bit definition.
*
* When specifying the debug output desired for non-error messages
* (the CHK_LVL parameter in the debug output macros), users must define
* all bits whose output they are interested in.
*
* SEE ALSO
* Debug Output, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE, CL_TRACE_EXIT
*********/
#if defined(_DEBUG_)
/****d* Component Library: Debug Output/CL_PRINT
* NAME
* CL_PRINT
*
* DESCRIPTION
* The CL_PRINT macro sends a string to the current debug target if
* the requested debug level matches the current debug level.
*
* SYNOPSIS
* CL_PRINT( DBG_LVL, CHK_LVL, STRING );
*
* PARAMETERS
* DBG_LVL
* [in] Debug level for the string to output
*
* CHK_LVL
* [in] Current debug level against which to check DBG_LVL
*
* STRING
* [in] String to send to the current debug target. The string includes
* parentheses in order to allow additional parameters.
*
* RETURN VALUE
* This macro does not return a value.
*
* EXAMPLE
* #define MY_FUNC_DBG_LVL 1
*
* uint32_t my_dbg_lvl = CL_DBG_ALL;
*
* void
* my_func()
* {
* CL_PRINT( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") );
* }
*
* RESULT
* Hello world!
*
* NOTES
* The requested string is printed only if all bits set in DBG_LVL are also
* set in CHK_LVL unless the most significant bit is set (indicating an
* error), in which case the lower bits are ignored. CHK_LVL may have
* additional bits set.
*
* In multi-processor environments where the current processor can be
* determined, the zero-based number of the processor on which the output
* is generated is prepended to the output.
*
* SEE ALSO
* Debug Output, Debug Levels, CL_ENTER, CL_EXIT, CL_TRACE, CL_TRACE_EXIT
*********/
#define CL_PRINT( DBG_LVL, CHK_LVL, STRING ) \
{ \
if( DBG_LVL & CL_DBG_ERROR ) \
cl_dbg_out STRING; \
else if( (DBG_LVL & CHK_LVL) == DBG_LVL ) \
cl_dbg_out STRING; \
}
/****d* Component Library: Debug Output/CL_ENTER
* NAME
* CL_ENTER
*
* DESCRIPTION
* The CL_ENTER macro marks the entrance into a function by sending a
* string to the current debug target if the requested debug level matches
* the current debug level.
*
* SYNOPSIS
* CL_ENTER( DBG_LVL, CHK_LVL );
*
* PARAMETERS
* DBG_LVL
* [in] Debug level for the string to output
*
* CHK_LVL
* [in] Current debug level against which to check DBG_LVL
*
* RETURN VALUE
* This macro does not return a value.
*
* EXAMPLE
* #define __MODULE__ "my_module"
* #define MY_FUNC_DBG_LVL 1
*
* uint32_t my_dbg_lvl = CL_DBG_ALL;
*
* void
* my_func()
* {
* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl );
* CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl );
* }
*
* RESULT
* my_module:my_func() [
* my_module:my_func() ]
*
* NOTES
* The function entrance notification is printed only if all bits set
* in DBG_LVL are also set in CHK_LVL. CHK_LVL may have additional bits set.
*
* If the __MODULE__ preprocessor keyword is defined, that keyword will be
* prepended to the function name, separated with a colon.
*
* In multi-processor environments where the current processor can be
* determined, the zero-based number of the processor on which the output
* is generated is prepended to the output.
*
* SEE ALSO
* Debug Output, Debug Levels, CL_PRINT, CL_EXIT, CL_TRACE, CL_TRACE_EXIT
*********/
#define CL_ENTER( DBG_LVL, CHK_LVL ) \
CL_CHK_STK; \
CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_ENTER );
/****d* Component Library: Debug Output/CL_EXIT
* NAME
* CL_EXIT
*
* DESCRIPTION
* The CL_EXIT macro marks the exit from a function by sending a string
* to the current debug target if the requested debug level matches the
* current debug level.
*
* SYNOPSIS
* CL_EXIT( DBG_LVL, CHK_LVL );
*
* PARAMETERS
* DBG_LVL
* [in] Debug level for the string to output
*
* CHK_LVL
* [in] Current debug level against which to check DBG_LVL
*
* RETURN VALUE
* This macro does not return a value.
*
* EXAMPLE
* #define __MODULE__ "my_module"
* #define MY_FUNC_DBG_LVL 1
*
* uint32_t my_dbg_lvl = CL_DBG_ALL;
*
* void
* my_func()
* {
* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl );
* CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl );
* }
*
* RESULT
* my_module:my_func() [
* my_module:my_func() ]
*
* NOTES
* The exit notification is printed only if all bits set in DBG_LVL are also
* set in CHK_LVL. CHK_LVL may have additional bits set.
*
* The CL_EXIT macro must only be used after the CL_ENTRY macro as it
* depends on that macro's implementation.
*
* If the __MODULE__ preprocessor keyword is defined, that keyword will be
* prepended to the function name, separated with a colon.
*
* In multi-processor environments where the current processor can be
* determined, the zero-based number of the processor on which the output
* is generated is prepended to the output.
*
* SEE ALSO
* Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_TRACE, CL_TRACE_EXIT
*********/
#define CL_EXIT( DBG_LVL, CHK_LVL ) \
CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_EXIT );
/****d* Component Library: Debug Output/CL_TRACE
* NAME
* CL_TRACE
*
* DESCRIPTION
* The CL_TRACE macro sends a string to the current debug target if
* the requested debug level matches the current debug level. The
* output is prepended with the function name and, depending on the
* debug level requested, an indication of the severity of the message.
*
* SYNOPSIS
* CL_TRACE( DBG_LVL, CHK_LVL, STRING );
*
* PARAMETERS
* DBG_LVL
* [in] Debug level for the string to output
*
* CHK_LVL
* [in] Current debug level against which to check DBG_LVL
*
* STRING
* [in] String to send to the current debug target. The string includes
* parentheses in order to allow additional parameters.
*
* RETURN VALUE
* This macro does not return a value.
*
* EXAMPLE
* #define __MODULE__ "my_module"
* #define MY_FUNC_DBG_LVL 1
*
* uint32_t my_dbg_lvl = CL_DBG_ALL;
*
* void
* my_func()
* {
* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl );
* CL_TRACE( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") );
* CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl );
* }
*
* RESULT
* my_module:my_func() [
* my_module:my_func(): Hello world!
* my_module:my_func() ]
*
* NOTES
* The requested string is printed only if all bits set in DBG_LVL are also
* set in CHK_LVL. CHK_LVL may have additional bits set.
*
* The CL_TRACE macro must only be used after the CL_ENTRY macro as it
* depends on that macro's implementation.
*
* If the DBG_LVL has the upper bit set, the output will contain
* an "!ERROR!" statement between the function name and STRING.
*
* If the __MODULE__ preprocessor keyword is defined, that keyword will be
* prepended to the function name, separated with a colon.
*
* In multi-processor environments where the current processor can be
* determined, the zero-based number of the processor on which the output
* is generated is prepended to the output.
*
* SEE ALSO
* Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE_EXIT
*********/
#define CL_TRACE( DBG_LVL, CHK_LVL, STRING ) \
{ \
switch( DBG_LVL & CL_DBG_ERROR ) \
{ \
case CL_DBG_ERROR: \
CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_ERROR ); \
break; \
default: \
CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_INFO ); \
break; \
} \
CL_PRINT( DBG_LVL, CHK_LVL, STRING ); \
}
/****d* Component Library: Debug Output/CL_TRACE_EXIT
* NAME
* CL_TRACE_EXIT
*
* DESCRIPTION
* The CL_TRACE_EXIT macro combines the functionality of the CL_TRACE and
* CL_EXIT macros, in that order.
*
* SYNOPSIS
* CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING );
*
* PARAMETERS
* DBG_LVL
* [in] Debug level for the string to output
*
* CHK_LVL
* [in] Current debug level against which to check DBG_LVL
*
* STRING
* [in] String to send to the current debug target. The string includes
* parentheses in order to allow additional parameters.
*
* RETURN VALUE
* This macro does not return a value.
*
* EXAMPLE
* #define __MODULE__ "my_module"
* #define MY_FUNC_DBG_LVL 1
*
* uint32_t my_dbg_lvl = CL_DBG_ALL;
*
* void
* my_func()
* {
* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl );
* CL_TRACE_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") );
* }
*
* RESULT
* my_module:my_func() [
* my_module:my_func(): Hello world!
* my_module:my_func() ]
*
* NOTES
* The requested string is printed only if all bits set in DBG_LVL are also
* set in CHK_LVL. CHK_LVL may have additional bits set.
*
* The CL_TRACE_EXIT macro must only be used after the CL_ENTRY macro as it
* depends on that macro's implementation.
*
* If the DBG_LVL has the upper bit set, the output will contain
* an "!ERROR!" statement between the function name and STRING.
*
* If the __MODULE__ preprocessor keyword is defined, that keyword will be
* prepended to the function name, separated with a colon.
*
* In multi-processor environments where the current processor can be
* determined, the zero-based number of the processor on which the output
* is generated is prepended to the output.
*
* SEE ALSO
* Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE
*********/
#define CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING ) \
CL_TRACE( DBG_LVL, CHK_LVL, STRING ); \
CL_EXIT( DBG_LVL, CHK_LVL );
#else /* defined(_DEBUG_) */
/* Define as NULL macros in a free build. */
#define CL_PRINT( DBG_LVL, CHK_LVL, STRING );
#define CL_ENTER( DBG_LVL, CHK_LVL );
#define CL_EXIT( DBG_LVL, CHK_LVL );
#define CL_TRACE( DBG_LVL, CHK_LVL, STRING );
#define CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING );
#endif /* defined(_DEBUG_) */
/****d* Component Library: Debug Output/64-bit Print Format
* NAME
* 64-bit Print Format
*
* DESCRIPTION
* The 64-bit print keywords allow users to use 64-bit values in debug or
* console output.
*
* Different platforms define 64-bit print formats differently. The 64-bit
* print formats exposed by the component library are supported in all
* platforms.
*
* VALUES
* PRId64
* Print a 64-bit integer in signed decimal format.
* PRIx64
* Print a 64-bit integer in hexadecimal format.
* PRIo64
* Print a 64-bit integer in octal format.
* PRIu64
* Print a 64-bit integer in unsigned decimal format.
*
* EXAMPLE
* uint64 MyVal = 2;
* // Print a 64-bit integer in hexadecimal format.
* cl_dbg_out( "MyVal: 0x%" PRIx64 "\n", MyVal );
*
* NOTES
* Standard print flags to specify padding and precision can still be used
* following the '%' sign in the string preceding the 64-bit print keyword.
*
* The above keywords are strings and make use of compilers' string
* concatenation ability.
*********/
void complib_init(void);
void complib_exit(void);
END_C_DECLS
#endif /* _CL_DEBUG_H_ */