Generated from ./inc/complib/cl_debug.h with ROBODoc v4.99.17 on Sun Mar 04 2007 18:17:52

[Modules] Component Library/Debug Output

[top][parent][index]

NAME

       Debug Output

DESCRIPTION

       The debug output functions and macros send debug messages to the current
       debug target.

[Definitions] Component Library: Debug Output/64-bit Print Format

[top][index]

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.

[Functions] Component Library: Debug Output/cl_break

[top][index]

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.

[Functions] Component Library: Debug Output/cl_dbg_out

[top][index]

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

[Definitions] Component Library: Debug Output/CL_ENTER

[top][index]

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

[Definitions] Component Library: Debug Output/CL_EXIT

[top][index]

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

[Functions] Component Library: Debug Output/cl_msg_out

[top][index]

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

[Definitions] Component Library: Debug Output/CL_PRINT

[top][index]

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

[Definitions] Component Library: Debug Output/CL_TRACE

[top][index]

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

[Definitions] Component Library: Debug Output/CL_TRACE_EXIT

[top][index]

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

[Definitions] Component Library: Debug Output/Debug Levels

[top][index]

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