NAME
Debug Output
DESCRIPTION
The debug output functions and macros send debug messages to the current debug target.
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.
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.
NAME
cl_dbg_out
DESCRIPTION
The cl_dbg_out function sends a debug message to the debug target in debug builds only.
SYNOPSIS
CL_EXPORT 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
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
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
NAME
cl_msg_out
DESCRIPTION
The cl_msg_out function sends a debug message to the message log target.
SYNOPSIS
CL_EXPORT 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
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
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
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
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