Generated from cl_debug.h with ROBODoc v3.2.3 on Sat Jan 18 07:05:17 2003
TABLE OF CONTENTS
- Component Library/Debug Output
- Component Library: Debug Output/64-bit Print Format
- Component Library: Debug Output/CL_ENTER
- Component Library: Debug Output/CL_EXIT
- Component Library: Debug Output/CL_PRINT
- Component Library: Debug Output/CL_TRACE
- Component Library: Debug Output/CL_TRACE_EXIT
- Component Library: Debug Output/Debug Levels
- Component Library: Debug Output/cl_break
- Component Library: Debug Output/cl_dbg_out
- Component Library: Debug Output/cl_msg_out
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_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, NAME );
PARAMETERS
DBG_LVL
[in] Debug level for the string to output
CHK_LVL
[in] Current debug level against which to check DBG_LVL
NAME
[in] Name of the function being executed
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, ("my_func") );
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.
The parentheses around the name are optional and may be included for
consistency with the other debug macros.
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, ("my_func") );
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_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, ("my_func") );
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, ("my_func") );
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
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
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_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