cl_debug.h revision 219820
1219820Sjeff/* 2219820Sjeff * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3219820Sjeff * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4219820Sjeff * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5219820Sjeff * 6219820Sjeff * This software is available to you under a choice of one of two 7219820Sjeff * licenses. You may choose to be licensed under the terms of the GNU 8219820Sjeff * General Public License (GPL) Version 2, available from the file 9219820Sjeff * COPYING in the main directory of this source tree, or the 10219820Sjeff * OpenIB.org BSD license below: 11219820Sjeff * 12219820Sjeff * Redistribution and use in source and binary forms, with or 13219820Sjeff * without modification, are permitted provided that the following 14219820Sjeff * conditions are met: 15219820Sjeff * 16219820Sjeff * - Redistributions of source code must retain the above 17219820Sjeff * copyright notice, this list of conditions and the following 18219820Sjeff * disclaimer. 19219820Sjeff * 20219820Sjeff * - Redistributions in binary form must reproduce the above 21219820Sjeff * copyright notice, this list of conditions and the following 22219820Sjeff * disclaimer in the documentation and/or other materials 23219820Sjeff * provided with the distribution. 24219820Sjeff * 25219820Sjeff * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26219820Sjeff * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27219820Sjeff * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28219820Sjeff * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29219820Sjeff * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30219820Sjeff * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31219820Sjeff * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32219820Sjeff * SOFTWARE. 33219820Sjeff * 34219820Sjeff */ 35219820Sjeff 36219820Sjeff/* 37219820Sjeff * Abstract: 38219820Sjeff * Declaration of functions for reporting debug output. 39219820Sjeff */ 40219820Sjeff 41219820Sjeff#ifndef _CL_DEBUG_H_ 42219820Sjeff#define _CL_DEBUG_H_ 43219820Sjeff 44219820Sjeff#include <complib/cl_debug_osd.h> 45219820Sjeff 46219820Sjeff#ifdef __cplusplus 47219820Sjeff# define BEGIN_C_DECLS extern "C" { 48219820Sjeff# define END_C_DECLS } 49219820Sjeff#else /* !__cplusplus */ 50219820Sjeff# define BEGIN_C_DECLS 51219820Sjeff# define END_C_DECLS 52219820Sjeff#endif /* __cplusplus */ 53219820Sjeff 54219820SjeffBEGIN_C_DECLS 55219820Sjeff/****h* Component Library/Debug Output 56219820Sjeff* NAME 57219820Sjeff* Debug Output 58219820Sjeff* 59219820Sjeff* DESCRIPTION 60219820Sjeff* The debug output functions and macros send debug messages to the current 61219820Sjeff* debug target. 62219820Sjeff*********/ 63219820Sjeff/****f* Component Library: Debug Output/cl_break 64219820Sjeff* NAME 65219820Sjeff* cl_break 66219820Sjeff* 67219820Sjeff* DESCRIPTION 68219820Sjeff* The cl_break function halts execution. 69219820Sjeff* 70219820Sjeff* SYNOPSIS 71219820Sjeff* void 72219820Sjeff* cl_break(); 73219820Sjeff* 74219820Sjeff* RETURN VALUE 75219820Sjeff* This function does not return a value. 76219820Sjeff* 77219820Sjeff* NOTES 78219820Sjeff* In a release build, cl_break has no effect. 79219820Sjeff*********/ 80219820Sjeff/****f* Component Library: Debug Output/cl_is_debug 81219820Sjeff* NAME 82219820Sjeff* cl_is_debug 83219820Sjeff* 84219820Sjeff* DESCRIPTION 85219820Sjeff* The cl_is_debug function returns TRUE if the complib was compiled 86219820Sjeff* in debug mode, and FALSE otherwise. 87219820Sjeff* 88219820Sjeff* SYNOPSIS 89219820Sjeff*/ 90219820Sjeffboolean_t cl_is_debug(void); 91219820Sjeff/* 92219820Sjeff* PARAMETERS 93219820Sjeff* None 94219820Sjeff* 95219820Sjeff* RETURN VALUE 96219820Sjeff* TRUE if compiled in debug version. FALSE otherwise. 97219820Sjeff* 98219820Sjeff* NOTES 99219820Sjeff* 100219820Sjeff*********/ 101219820Sjeff 102219820Sjeff#if defined( _DEBUG_ ) 103219820Sjeff#ifndef cl_dbg_out 104219820Sjeff/****f* Component Library: Debug Output/cl_dbg_out 105219820Sjeff* NAME 106219820Sjeff* cl_dbg_out 107219820Sjeff* 108219820Sjeff* DESCRIPTION 109219820Sjeff* The cl_dbg_out function sends a debug message to the debug target in 110219820Sjeff* debug builds only. 111219820Sjeff* 112219820Sjeff* SYNOPSIS 113219820Sjeff*/ 114219820Sjeffvoid cl_dbg_out(IN const char *const debug_message, IN ...); 115219820Sjeff/* 116219820Sjeff* PARAMETERS 117219820Sjeff* debug_message 118219820Sjeff* [in] ANSI string formatted identically as for a call to the standard C 119219820Sjeff* function printf. 120219820Sjeff* 121219820Sjeff* ... 122219820Sjeff* [in] Extra parameters for string formatting, as defined for the 123219820Sjeff* standard C function printf. 124219820Sjeff* 125219820Sjeff* RETURN VALUE 126219820Sjeff* This function does not return a value. 127219820Sjeff* 128219820Sjeff* NOTES 129219820Sjeff* In a release build, cl_dbg_out has no effect. 130219820Sjeff* 131219820Sjeff* The formatting of the debug_message string is the same as for printf 132219820Sjeff* 133219820Sjeff* cl_dbg_out sends the debug message to the current debug target. 134219820Sjeff* 135219820Sjeff* SEE ALSO 136219820Sjeff* Debug Output, cl_msg_out 137219820Sjeff*********/ 138219820Sjeff#endif 139219820Sjeff#else 140219820Sjeffstatic inline void cl_dbg_out(IN const char *const debug_message, IN ...) 141219820Sjeff{ 142219820Sjeff UNUSED_PARAM(debug_message); 143219820Sjeff} 144219820Sjeff#endif /* defined( _DEBUG_ ) */ 145219820Sjeff 146219820Sjeff#ifndef cl_msg_out 147219820Sjeff/****f* Component Library: Debug Output/cl_msg_out 148219820Sjeff* NAME 149219820Sjeff* cl_msg_out 150219820Sjeff* 151219820Sjeff* DESCRIPTION 152219820Sjeff* The cl_msg_out function sends a debug message to the message log target. 153219820Sjeff* 154219820Sjeff* SYNOPSIS 155219820Sjeff*/ 156219820Sjeffvoid cl_msg_out(IN const char *const message, IN ...); 157219820Sjeff/* 158219820Sjeff* PARAMETERS 159219820Sjeff* message 160219820Sjeff* [in] ANSI string formatted identically as for a call to the standard C 161219820Sjeff* function printf. 162219820Sjeff* 163219820Sjeff* ... 164219820Sjeff* [in] Extra parameters for string formatting, as defined for the 165219820Sjeff* standard C function printf. 166219820Sjeff* 167219820Sjeff* RETURN VALUE 168219820Sjeff* This function does not return a value. 169219820Sjeff* 170219820Sjeff* NOTES 171219820Sjeff* cl_msg_out is available in both debug and release builds. 172219820Sjeff* 173219820Sjeff* The formatting of the message string is the same as for printf 174219820Sjeff* 175219820Sjeff* cl_msg_out sends the message to the current message logging target. 176219820Sjeff* 177219820Sjeff* SEE ALSO 178219820Sjeff* Debug Output, cl_dbg_out 179219820Sjeff*********/ 180219820Sjeff#endif 181219820Sjeff 182219820Sjeff/****d* Component Library: Debug Output/Debug Levels 183219820Sjeff* NAME 184219820Sjeff* Debug Levels 185219820Sjeff* 186219820Sjeff* DESCRIPTION 187219820Sjeff* The debug output macros reserve the upper bit of the debug level to 188219820Sjeff* convey an error. 189219820Sjeff* 190219820Sjeff* SYNOPSIS 191219820Sjeff*/ 192219820Sjeff#define CL_DBG_DISABLE 0 193219820Sjeff#define CL_DBG_ERROR 0x80000000 194219820Sjeff#define CL_DBG_ALL 0xFFFFFFFF 195219820Sjeff/* 196219820Sjeff* VALUES 197219820Sjeff* CL_DBG_DISABLE 198219820Sjeff* Disable all debug output, including errors. 199219820Sjeff* 200219820Sjeff* CL_DBG_ERROR 201219820Sjeff* Enable error debug output. 202219820Sjeff* 203219820Sjeff* CL_DBG_ALL 204219820Sjeff* Enbale all debug output. 205219820Sjeff* 206219820Sjeff* NOTES 207219820Sjeff* Users can define custom debug levels using the lower 31 bits of their 208219820Sjeff* debug level to control non-error debug output. Error messages are 209219820Sjeff* always displayed, regardless of the lower bit definition. 210219820Sjeff* 211219820Sjeff* When specifying the debug output desired for non-error messages 212219820Sjeff* (the CHK_LVL parameter in the debug output macros), users must define 213219820Sjeff* all bits whose output they are interested in. 214219820Sjeff* 215219820Sjeff* SEE ALSO 216219820Sjeff* Debug Output, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE, CL_TRACE_EXIT 217219820Sjeff*********/ 218219820Sjeff 219219820Sjeff#if defined(_DEBUG_) 220219820Sjeff 221219820Sjeff/****d* Component Library: Debug Output/CL_PRINT 222219820Sjeff* NAME 223219820Sjeff* CL_PRINT 224219820Sjeff* 225219820Sjeff* DESCRIPTION 226219820Sjeff* The CL_PRINT macro sends a string to the current debug target if 227219820Sjeff* the requested debug level matches the current debug level. 228219820Sjeff* 229219820Sjeff* SYNOPSIS 230219820Sjeff* CL_PRINT( DBG_LVL, CHK_LVL, STRING ); 231219820Sjeff* 232219820Sjeff* PARAMETERS 233219820Sjeff* DBG_LVL 234219820Sjeff* [in] Debug level for the string to output 235219820Sjeff* 236219820Sjeff* CHK_LVL 237219820Sjeff* [in] Current debug level against which to check DBG_LVL 238219820Sjeff* 239219820Sjeff* STRING 240219820Sjeff* [in] String to send to the current debug target. The string includes 241219820Sjeff* parentheses in order to allow additional parameters. 242219820Sjeff* 243219820Sjeff* RETURN VALUE 244219820Sjeff* This macro does not return a value. 245219820Sjeff* 246219820Sjeff* EXAMPLE 247219820Sjeff* #define MY_FUNC_DBG_LVL 1 248219820Sjeff* 249219820Sjeff* uint32_t my_dbg_lvl = CL_DBG_ALL; 250219820Sjeff* 251219820Sjeff* void 252219820Sjeff* my_func() 253219820Sjeff* { 254219820Sjeff* CL_PRINT( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") ); 255219820Sjeff* } 256219820Sjeff* 257219820Sjeff* RESULT 258219820Sjeff* Hello world! 259219820Sjeff* 260219820Sjeff* NOTES 261219820Sjeff* The requested string is printed only if all bits set in DBG_LVL are also 262219820Sjeff* set in CHK_LVL unless the most significant bit is set (indicating an 263219820Sjeff* error), in which case the lower bits are ignored. CHK_LVL may have 264219820Sjeff* additional bits set. 265219820Sjeff* 266219820Sjeff* In multi-processor environments where the current processor can be 267219820Sjeff* determined, the zero-based number of the processor on which the output 268219820Sjeff* is generated is prepended to the output. 269219820Sjeff* 270219820Sjeff* SEE ALSO 271219820Sjeff* Debug Output, Debug Levels, CL_ENTER, CL_EXIT, CL_TRACE, CL_TRACE_EXIT 272219820Sjeff*********/ 273219820Sjeff#define CL_PRINT( DBG_LVL, CHK_LVL, STRING ) \ 274219820Sjeff { \ 275219820Sjeff if( DBG_LVL & CL_DBG_ERROR ) \ 276219820Sjeff cl_dbg_out STRING; \ 277219820Sjeff else if( (DBG_LVL & CHK_LVL) == DBG_LVL ) \ 278219820Sjeff cl_dbg_out STRING; \ 279219820Sjeff } 280219820Sjeff 281219820Sjeff/****d* Component Library: Debug Output/CL_ENTER 282219820Sjeff* NAME 283219820Sjeff* CL_ENTER 284219820Sjeff* 285219820Sjeff* DESCRIPTION 286219820Sjeff* The CL_ENTER macro marks the entrance into a function by sending a 287219820Sjeff* string to the current debug target if the requested debug level matches 288219820Sjeff* the current debug level. 289219820Sjeff* 290219820Sjeff* SYNOPSIS 291219820Sjeff* CL_ENTER( DBG_LVL, CHK_LVL ); 292219820Sjeff* 293219820Sjeff* PARAMETERS 294219820Sjeff* DBG_LVL 295219820Sjeff* [in] Debug level for the string to output 296219820Sjeff* 297219820Sjeff* CHK_LVL 298219820Sjeff* [in] Current debug level against which to check DBG_LVL 299219820Sjeff* 300219820Sjeff* RETURN VALUE 301219820Sjeff* This macro does not return a value. 302219820Sjeff* 303219820Sjeff* EXAMPLE 304219820Sjeff* #define __MODULE__ "my_module" 305219820Sjeff* #define MY_FUNC_DBG_LVL 1 306219820Sjeff* 307219820Sjeff* uint32_t my_dbg_lvl = CL_DBG_ALL; 308219820Sjeff* 309219820Sjeff* void 310219820Sjeff* my_func() 311219820Sjeff* { 312219820Sjeff* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl ); 313219820Sjeff* CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl ); 314219820Sjeff* } 315219820Sjeff* 316219820Sjeff* RESULT 317219820Sjeff* my_module:my_func() [ 318219820Sjeff* my_module:my_func() ] 319219820Sjeff* 320219820Sjeff* NOTES 321219820Sjeff* The function entrance notification is printed only if all bits set 322219820Sjeff* in DBG_LVL are also set in CHK_LVL. CHK_LVL may have additional bits set. 323219820Sjeff* 324219820Sjeff* If the __MODULE__ preprocessor keyword is defined, that keyword will be 325219820Sjeff* prepended to the function name, separated with a colon. 326219820Sjeff* 327219820Sjeff* In multi-processor environments where the current processor can be 328219820Sjeff* determined, the zero-based number of the processor on which the output 329219820Sjeff* is generated is prepended to the output. 330219820Sjeff* 331219820Sjeff* SEE ALSO 332219820Sjeff* Debug Output, Debug Levels, CL_PRINT, CL_EXIT, CL_TRACE, CL_TRACE_EXIT 333219820Sjeff*********/ 334219820Sjeff#define CL_ENTER( DBG_LVL, CHK_LVL ) \ 335219820Sjeff CL_CHK_STK; \ 336219820Sjeff CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_ENTER ); 337219820Sjeff 338219820Sjeff/****d* Component Library: Debug Output/CL_EXIT 339219820Sjeff* NAME 340219820Sjeff* CL_EXIT 341219820Sjeff* 342219820Sjeff* DESCRIPTION 343219820Sjeff* The CL_EXIT macro marks the exit from a function by sending a string 344219820Sjeff* to the current debug target if the requested debug level matches the 345219820Sjeff* current debug level. 346219820Sjeff* 347219820Sjeff* SYNOPSIS 348219820Sjeff* CL_EXIT( DBG_LVL, CHK_LVL ); 349219820Sjeff* 350219820Sjeff* PARAMETERS 351219820Sjeff* DBG_LVL 352219820Sjeff* [in] Debug level for the string to output 353219820Sjeff* 354219820Sjeff* CHK_LVL 355219820Sjeff* [in] Current debug level against which to check DBG_LVL 356219820Sjeff* 357219820Sjeff* RETURN VALUE 358219820Sjeff* This macro does not return a value. 359219820Sjeff* 360219820Sjeff* EXAMPLE 361219820Sjeff* #define __MODULE__ "my_module" 362219820Sjeff* #define MY_FUNC_DBG_LVL 1 363219820Sjeff* 364219820Sjeff* uint32_t my_dbg_lvl = CL_DBG_ALL; 365219820Sjeff* 366219820Sjeff* void 367219820Sjeff* my_func() 368219820Sjeff* { 369219820Sjeff* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl ); 370219820Sjeff* CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl ); 371219820Sjeff* } 372219820Sjeff* 373219820Sjeff* RESULT 374219820Sjeff* my_module:my_func() [ 375219820Sjeff* my_module:my_func() ] 376219820Sjeff* 377219820Sjeff* NOTES 378219820Sjeff* The exit notification is printed only if all bits set in DBG_LVL are also 379219820Sjeff* set in CHK_LVL. CHK_LVL may have additional bits set. 380219820Sjeff* 381219820Sjeff* The CL_EXIT macro must only be used after the CL_ENTRY macro as it 382219820Sjeff* depends on that macro's implementation. 383219820Sjeff* 384219820Sjeff* If the __MODULE__ preprocessor keyword is defined, that keyword will be 385219820Sjeff* prepended to the function name, separated with a colon. 386219820Sjeff* 387219820Sjeff* In multi-processor environments where the current processor can be 388219820Sjeff* determined, the zero-based number of the processor on which the output 389219820Sjeff* is generated is prepended to the output. 390219820Sjeff* 391219820Sjeff* SEE ALSO 392219820Sjeff* Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_TRACE, CL_TRACE_EXIT 393219820Sjeff*********/ 394219820Sjeff#define CL_EXIT( DBG_LVL, CHK_LVL ) \ 395219820Sjeff CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_EXIT ); 396219820Sjeff 397219820Sjeff/****d* Component Library: Debug Output/CL_TRACE 398219820Sjeff* NAME 399219820Sjeff* CL_TRACE 400219820Sjeff* 401219820Sjeff* DESCRIPTION 402219820Sjeff* The CL_TRACE macro sends a string to the current debug target if 403219820Sjeff* the requested debug level matches the current debug level. The 404219820Sjeff* output is prepended with the function name and, depending on the 405219820Sjeff* debug level requested, an indication of the severity of the message. 406219820Sjeff* 407219820Sjeff* SYNOPSIS 408219820Sjeff* CL_TRACE( DBG_LVL, CHK_LVL, STRING ); 409219820Sjeff* 410219820Sjeff* PARAMETERS 411219820Sjeff* DBG_LVL 412219820Sjeff* [in] Debug level for the string to output 413219820Sjeff* 414219820Sjeff* CHK_LVL 415219820Sjeff* [in] Current debug level against which to check DBG_LVL 416219820Sjeff* 417219820Sjeff* STRING 418219820Sjeff* [in] String to send to the current debug target. The string includes 419219820Sjeff* parentheses in order to allow additional parameters. 420219820Sjeff* 421219820Sjeff* RETURN VALUE 422219820Sjeff* This macro does not return a value. 423219820Sjeff* 424219820Sjeff* EXAMPLE 425219820Sjeff* #define __MODULE__ "my_module" 426219820Sjeff* #define MY_FUNC_DBG_LVL 1 427219820Sjeff* 428219820Sjeff* uint32_t my_dbg_lvl = CL_DBG_ALL; 429219820Sjeff* 430219820Sjeff* void 431219820Sjeff* my_func() 432219820Sjeff* { 433219820Sjeff* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl ); 434219820Sjeff* CL_TRACE( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") ); 435219820Sjeff* CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl ); 436219820Sjeff* } 437219820Sjeff* 438219820Sjeff* RESULT 439219820Sjeff* my_module:my_func() [ 440219820Sjeff* my_module:my_func(): Hello world! 441219820Sjeff* my_module:my_func() ] 442219820Sjeff* 443219820Sjeff* NOTES 444219820Sjeff* The requested string is printed only if all bits set in DBG_LVL are also 445219820Sjeff* set in CHK_LVL. CHK_LVL may have additional bits set. 446219820Sjeff* 447219820Sjeff* The CL_TRACE macro must only be used after the CL_ENTRY macro as it 448219820Sjeff* depends on that macro's implementation. 449219820Sjeff* 450219820Sjeff* If the DBG_LVL has the upper bit set, the output will contain 451219820Sjeff* an "!ERROR!" statement between the function name and STRING. 452219820Sjeff* 453219820Sjeff* If the __MODULE__ preprocessor keyword is defined, that keyword will be 454219820Sjeff* prepended to the function name, separated with a colon. 455219820Sjeff* 456219820Sjeff* In multi-processor environments where the current processor can be 457219820Sjeff* determined, the zero-based number of the processor on which the output 458219820Sjeff* is generated is prepended to the output. 459219820Sjeff* 460219820Sjeff* SEE ALSO 461219820Sjeff* Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE_EXIT 462219820Sjeff*********/ 463219820Sjeff#define CL_TRACE( DBG_LVL, CHK_LVL, STRING ) \ 464219820Sjeff{ \ 465219820Sjeffswitch( DBG_LVL & CL_DBG_ERROR ) \ 466219820Sjeff{ \ 467219820Sjeff case CL_DBG_ERROR: \ 468219820Sjeff CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_ERROR ); \ 469219820Sjeff break; \ 470219820Sjeff default: \ 471219820Sjeff CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_INFO ); \ 472219820Sjeff break; \ 473219820Sjeff} \ 474219820SjeffCL_PRINT( DBG_LVL, CHK_LVL, STRING ); \ 475219820Sjeff} 476219820Sjeff 477219820Sjeff/****d* Component Library: Debug Output/CL_TRACE_EXIT 478219820Sjeff* NAME 479219820Sjeff* CL_TRACE_EXIT 480219820Sjeff* 481219820Sjeff* DESCRIPTION 482219820Sjeff* The CL_TRACE_EXIT macro combines the functionality of the CL_TRACE and 483219820Sjeff* CL_EXIT macros, in that order. 484219820Sjeff* 485219820Sjeff* SYNOPSIS 486219820Sjeff* CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING ); 487219820Sjeff* 488219820Sjeff* PARAMETERS 489219820Sjeff* DBG_LVL 490219820Sjeff* [in] Debug level for the string to output 491219820Sjeff* 492219820Sjeff* CHK_LVL 493219820Sjeff* [in] Current debug level against which to check DBG_LVL 494219820Sjeff* 495219820Sjeff* STRING 496219820Sjeff* [in] String to send to the current debug target. The string includes 497219820Sjeff* parentheses in order to allow additional parameters. 498219820Sjeff* 499219820Sjeff* RETURN VALUE 500219820Sjeff* This macro does not return a value. 501219820Sjeff* 502219820Sjeff* EXAMPLE 503219820Sjeff* #define __MODULE__ "my_module" 504219820Sjeff* #define MY_FUNC_DBG_LVL 1 505219820Sjeff* 506219820Sjeff* uint32_t my_dbg_lvl = CL_DBG_ALL; 507219820Sjeff* 508219820Sjeff* void 509219820Sjeff* my_func() 510219820Sjeff* { 511219820Sjeff* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl ); 512219820Sjeff* CL_TRACE_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") ); 513219820Sjeff* } 514219820Sjeff* 515219820Sjeff* RESULT 516219820Sjeff* my_module:my_func() [ 517219820Sjeff* my_module:my_func(): Hello world! 518219820Sjeff* my_module:my_func() ] 519219820Sjeff* 520219820Sjeff* NOTES 521219820Sjeff* The requested string is printed only if all bits set in DBG_LVL are also 522219820Sjeff* set in CHK_LVL. CHK_LVL may have additional bits set. 523219820Sjeff* 524219820Sjeff* The CL_TRACE_EXIT macro must only be used after the CL_ENTRY macro as it 525219820Sjeff* depends on that macro's implementation. 526219820Sjeff* 527219820Sjeff* If the DBG_LVL has the upper bit set, the output will contain 528219820Sjeff* an "!ERROR!" statement between the function name and STRING. 529219820Sjeff* 530219820Sjeff* If the __MODULE__ preprocessor keyword is defined, that keyword will be 531219820Sjeff* prepended to the function name, separated with a colon. 532219820Sjeff* 533219820Sjeff* In multi-processor environments where the current processor can be 534219820Sjeff* determined, the zero-based number of the processor on which the output 535219820Sjeff* is generated is prepended to the output. 536219820Sjeff* 537219820Sjeff* SEE ALSO 538219820Sjeff* Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE 539219820Sjeff*********/ 540219820Sjeff#define CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING ) \ 541219820Sjeff CL_TRACE( DBG_LVL, CHK_LVL, STRING ); \ 542219820Sjeff CL_EXIT( DBG_LVL, CHK_LVL ); 543219820Sjeff 544219820Sjeff#else /* defined(_DEBUG_) */ 545219820Sjeff 546219820Sjeff/* Define as NULL macros in a free build. */ 547219820Sjeff#define CL_PRINT( DBG_LVL, CHK_LVL, STRING ); 548219820Sjeff#define CL_ENTER( DBG_LVL, CHK_LVL ); 549219820Sjeff#define CL_EXIT( DBG_LVL, CHK_LVL ); 550219820Sjeff#define CL_TRACE( DBG_LVL, CHK_LVL, STRING ); 551219820Sjeff#define CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING ); 552219820Sjeff 553219820Sjeff#endif /* defined(_DEBUG_) */ 554219820Sjeff 555219820Sjeff/****d* Component Library: Debug Output/64-bit Print Format 556219820Sjeff* NAME 557219820Sjeff* 64-bit Print Format 558219820Sjeff* 559219820Sjeff* DESCRIPTION 560219820Sjeff* The 64-bit print keywords allow users to use 64-bit values in debug or 561219820Sjeff* console output. 562219820Sjeff* 563219820Sjeff* Different platforms define 64-bit print formats differently. The 64-bit 564219820Sjeff* print formats exposed by the component library are supported in all 565219820Sjeff* platforms. 566219820Sjeff* 567219820Sjeff* VALUES 568219820Sjeff* PRId64 569219820Sjeff* Print a 64-bit integer in signed decimal format. 570219820Sjeff* PRIx64 571219820Sjeff* Print a 64-bit integer in hexadecimal format. 572219820Sjeff* PRIo64 573219820Sjeff* Print a 64-bit integer in octal format. 574219820Sjeff* PRIu64 575219820Sjeff* Print a 64-bit integer in unsigned decimal format. 576219820Sjeff* 577219820Sjeff* EXAMPLE 578219820Sjeff* uint64 MyVal = 2; 579219820Sjeff* // Print a 64-bit integer in hexadecimal format. 580219820Sjeff* cl_dbg_out( "MyVal: 0x%" PRIx64 "\n", MyVal ); 581219820Sjeff* 582219820Sjeff* NOTES 583219820Sjeff* Standard print flags to specify padding and precision can still be used 584219820Sjeff* following the '%' sign in the string preceding the 64-bit print keyword. 585219820Sjeff* 586219820Sjeff* The above keywords are strings and make use of compilers' string 587219820Sjeff* concatenation ability. 588219820Sjeff*********/ 589219820Sjeffvoid complib_init(void); 590219820Sjeff 591219820Sjeffvoid complib_exit(void); 592219820Sjeff 593219820SjeffEND_C_DECLS 594219820Sjeff#endif /* _CL_DEBUG_H_ */ 595