1/* 2 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5 * 6 * This software is available to you under a choice of one of two 7 * licenses. You may choose to be licensed under the terms of the GNU 8 * General Public License (GPL) Version 2, available from the file 9 * COPYING in the main directory of this source tree, or the 10 * OpenIB.org BSD license below: 11 * 12 * Redistribution and use in source and binary forms, with or 13 * without modification, are permitted provided that the following 14 * conditions are met: 15 * 16 * - Redistributions of source code must retain the above 17 * copyright notice, this list of conditions and the following 18 * disclaimer. 19 * 20 * - Redistributions in binary form must reproduce the above 21 * copyright notice, this list of conditions and the following 22 * disclaimer in the documentation and/or other materials 23 * provided with the distribution. 24 * 25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32 * SOFTWARE. 33 * 34 */ 35 36/* 37 * Abstract: 38 * Declaration of functions for reporting debug output. 39 */ 40 41#ifndef _CL_DEBUG_H_ 42#define _CL_DEBUG_H_ 43 44#include <complib/cl_debug_osd.h> 45 46#ifdef __cplusplus 47# define BEGIN_C_DECLS extern "C" { 48# define END_C_DECLS } 49#else /* !__cplusplus */ 50# define BEGIN_C_DECLS 51# define END_C_DECLS 52#endif /* __cplusplus */ 53 54BEGIN_C_DECLS 55/****h* Component Library/Debug Output 56* NAME 57* Debug Output 58* 59* DESCRIPTION 60* The debug output functions and macros send debug messages to the current 61* debug target. 62*********/ 63/****f* Component Library: Debug Output/cl_break 64* NAME 65* cl_break 66* 67* DESCRIPTION 68* The cl_break function halts execution. 69* 70* SYNOPSIS 71* void 72* cl_break(); 73* 74* RETURN VALUE 75* This function does not return a value. 76* 77* NOTES 78* In a release build, cl_break has no effect. 79*********/ 80/****f* Component Library: Debug Output/cl_is_debug 81* NAME 82* cl_is_debug 83* 84* DESCRIPTION 85* The cl_is_debug function returns TRUE if the complib was compiled 86* in debug mode, and FALSE otherwise. 87* 88* SYNOPSIS 89*/ 90boolean_t cl_is_debug(void); 91/* 92* PARAMETERS 93* None 94* 95* RETURN VALUE 96* TRUE if compiled in debug version. FALSE otherwise. 97* 98* NOTES 99* 100*********/ 101 102#if defined( _DEBUG_ ) 103#ifndef cl_dbg_out 104/****f* Component Library: Debug Output/cl_dbg_out 105* NAME 106* cl_dbg_out 107* 108* DESCRIPTION 109* The cl_dbg_out function sends a debug message to the debug target in 110* debug builds only. 111* 112* SYNOPSIS 113*/ 114void cl_dbg_out(IN const char *const debug_message, IN ...); 115/* 116* PARAMETERS 117* debug_message 118* [in] ANSI string formatted identically as for a call to the standard C 119* function printf. 120* 121* ... 122* [in] Extra parameters for string formatting, as defined for the 123* standard C function printf. 124* 125* RETURN VALUE 126* This function does not return a value. 127* 128* NOTES 129* In a release build, cl_dbg_out has no effect. 130* 131* The formatting of the debug_message string is the same as for printf 132* 133* cl_dbg_out sends the debug message to the current debug target. 134* 135* SEE ALSO 136* Debug Output, cl_msg_out 137*********/ 138#endif 139#else 140static inline void cl_dbg_out(IN const char *const debug_message, IN ...) 141{ 142 UNUSED_PARAM(debug_message); 143} 144#endif /* defined( _DEBUG_ ) */ 145 146#ifndef cl_msg_out 147/****f* Component Library: Debug Output/cl_msg_out 148* NAME 149* cl_msg_out 150* 151* DESCRIPTION 152* The cl_msg_out function sends a debug message to the message log target. 153* 154* SYNOPSIS 155*/ 156void cl_msg_out(IN const char *const message, IN ...); 157/* 158* PARAMETERS 159* message 160* [in] ANSI string formatted identically as for a call to the standard C 161* function printf. 162* 163* ... 164* [in] Extra parameters for string formatting, as defined for the 165* standard C function printf. 166* 167* RETURN VALUE 168* This function does not return a value. 169* 170* NOTES 171* cl_msg_out is available in both debug and release builds. 172* 173* The formatting of the message string is the same as for printf 174* 175* cl_msg_out sends the message to the current message logging target. 176* 177* SEE ALSO 178* Debug Output, cl_dbg_out 179*********/ 180#endif 181 182/****d* Component Library: Debug Output/Debug Levels 183* NAME 184* Debug Levels 185* 186* DESCRIPTION 187* The debug output macros reserve the upper bit of the debug level to 188* convey an error. 189* 190* SYNOPSIS 191*/ 192#define CL_DBG_DISABLE 0 193#define CL_DBG_ERROR 0x80000000 194#define CL_DBG_ALL 0xFFFFFFFF 195/* 196* VALUES 197* CL_DBG_DISABLE 198* Disable all debug output, including errors. 199* 200* CL_DBG_ERROR 201* Enable error debug output. 202* 203* CL_DBG_ALL 204* Enbale all debug output. 205* 206* NOTES 207* Users can define custom debug levels using the lower 31 bits of their 208* debug level to control non-error debug output. Error messages are 209* always displayed, regardless of the lower bit definition. 210* 211* When specifying the debug output desired for non-error messages 212* (the CHK_LVL parameter in the debug output macros), users must define 213* all bits whose output they are interested in. 214* 215* SEE ALSO 216* Debug Output, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE, CL_TRACE_EXIT 217*********/ 218 219#if defined(_DEBUG_) 220 221/****d* Component Library: Debug Output/CL_PRINT 222* NAME 223* CL_PRINT 224* 225* DESCRIPTION 226* The CL_PRINT macro sends a string to the current debug target if 227* the requested debug level matches the current debug level. 228* 229* SYNOPSIS 230* CL_PRINT( DBG_LVL, CHK_LVL, STRING ); 231* 232* PARAMETERS 233* DBG_LVL 234* [in] Debug level for the string to output 235* 236* CHK_LVL 237* [in] Current debug level against which to check DBG_LVL 238* 239* STRING 240* [in] String to send to the current debug target. The string includes 241* parentheses in order to allow additional parameters. 242* 243* RETURN VALUE 244* This macro does not return a value. 245* 246* EXAMPLE 247* #define MY_FUNC_DBG_LVL 1 248* 249* uint32_t my_dbg_lvl = CL_DBG_ALL; 250* 251* void 252* my_func() 253* { 254* CL_PRINT( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") ); 255* } 256* 257* RESULT 258* Hello world! 259* 260* NOTES 261* The requested string is printed only if all bits set in DBG_LVL are also 262* set in CHK_LVL unless the most significant bit is set (indicating an 263* error), in which case the lower bits are ignored. CHK_LVL may have 264* additional bits set. 265* 266* In multi-processor environments where the current processor can be 267* determined, the zero-based number of the processor on which the output 268* is generated is prepended to the output. 269* 270* SEE ALSO 271* Debug Output, Debug Levels, CL_ENTER, CL_EXIT, CL_TRACE, CL_TRACE_EXIT 272*********/ 273#define CL_PRINT( DBG_LVL, CHK_LVL, STRING ) \ 274 { \ 275 if( DBG_LVL & CL_DBG_ERROR ) \ 276 cl_dbg_out STRING; \ 277 else if( (DBG_LVL & CHK_LVL) == DBG_LVL ) \ 278 cl_dbg_out STRING; \ 279 } 280 281/****d* Component Library: Debug Output/CL_ENTER 282* NAME 283* CL_ENTER 284* 285* DESCRIPTION 286* The CL_ENTER macro marks the entrance into a function by sending a 287* string to the current debug target if the requested debug level matches 288* the current debug level. 289* 290* SYNOPSIS 291* CL_ENTER( DBG_LVL, CHK_LVL ); 292* 293* PARAMETERS 294* DBG_LVL 295* [in] Debug level for the string to output 296* 297* CHK_LVL 298* [in] Current debug level against which to check DBG_LVL 299* 300* RETURN VALUE 301* This macro does not return a value. 302* 303* EXAMPLE 304* #define __MODULE__ "my_module" 305* #define MY_FUNC_DBG_LVL 1 306* 307* uint32_t my_dbg_lvl = CL_DBG_ALL; 308* 309* void 310* my_func() 311* { 312* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl ); 313* CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl ); 314* } 315* 316* RESULT 317* my_module:my_func() [ 318* my_module:my_func() ] 319* 320* NOTES 321* The function entrance notification is printed only if all bits set 322* in DBG_LVL are also set in CHK_LVL. CHK_LVL may have additional bits set. 323* 324* If the __MODULE__ preprocessor keyword is defined, that keyword will be 325* prepended to the function name, separated with a colon. 326* 327* In multi-processor environments where the current processor can be 328* determined, the zero-based number of the processor on which the output 329* is generated is prepended to the output. 330* 331* SEE ALSO 332* Debug Output, Debug Levels, CL_PRINT, CL_EXIT, CL_TRACE, CL_TRACE_EXIT 333*********/ 334#define CL_ENTER( DBG_LVL, CHK_LVL ) \ 335 CL_CHK_STK; \ 336 CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_ENTER ); 337 338/****d* Component Library: Debug Output/CL_EXIT 339* NAME 340* CL_EXIT 341* 342* DESCRIPTION 343* The CL_EXIT macro marks the exit from a function by sending a string 344* to the current debug target if the requested debug level matches the 345* current debug level. 346* 347* SYNOPSIS 348* CL_EXIT( DBG_LVL, CHK_LVL ); 349* 350* PARAMETERS 351* DBG_LVL 352* [in] Debug level for the string to output 353* 354* CHK_LVL 355* [in] Current debug level against which to check DBG_LVL 356* 357* RETURN VALUE 358* This macro does not return a value. 359* 360* EXAMPLE 361* #define __MODULE__ "my_module" 362* #define MY_FUNC_DBG_LVL 1 363* 364* uint32_t my_dbg_lvl = CL_DBG_ALL; 365* 366* void 367* my_func() 368* { 369* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl ); 370* CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl ); 371* } 372* 373* RESULT 374* my_module:my_func() [ 375* my_module:my_func() ] 376* 377* NOTES 378* The exit notification is printed only if all bits set in DBG_LVL are also 379* set in CHK_LVL. CHK_LVL may have additional bits set. 380* 381* The CL_EXIT macro must only be used after the CL_ENTRY macro as it 382* depends on that macro's implementation. 383* 384* If the __MODULE__ preprocessor keyword is defined, that keyword will be 385* prepended to the function name, separated with a colon. 386* 387* In multi-processor environments where the current processor can be 388* determined, the zero-based number of the processor on which the output 389* is generated is prepended to the output. 390* 391* SEE ALSO 392* Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_TRACE, CL_TRACE_EXIT 393*********/ 394#define CL_EXIT( DBG_LVL, CHK_LVL ) \ 395 CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_EXIT ); 396 397/****d* Component Library: Debug Output/CL_TRACE 398* NAME 399* CL_TRACE 400* 401* DESCRIPTION 402* The CL_TRACE macro sends a string to the current debug target if 403* the requested debug level matches the current debug level. The 404* output is prepended with the function name and, depending on the 405* debug level requested, an indication of the severity of the message. 406* 407* SYNOPSIS 408* CL_TRACE( DBG_LVL, CHK_LVL, STRING ); 409* 410* PARAMETERS 411* DBG_LVL 412* [in] Debug level for the string to output 413* 414* CHK_LVL 415* [in] Current debug level against which to check DBG_LVL 416* 417* STRING 418* [in] String to send to the current debug target. The string includes 419* parentheses in order to allow additional parameters. 420* 421* RETURN VALUE 422* This macro does not return a value. 423* 424* EXAMPLE 425* #define __MODULE__ "my_module" 426* #define MY_FUNC_DBG_LVL 1 427* 428* uint32_t my_dbg_lvl = CL_DBG_ALL; 429* 430* void 431* my_func() 432* { 433* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl ); 434* CL_TRACE( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") ); 435* CL_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl ); 436* } 437* 438* RESULT 439* my_module:my_func() [ 440* my_module:my_func(): Hello world! 441* my_module:my_func() ] 442* 443* NOTES 444* The requested string is printed only if all bits set in DBG_LVL are also 445* set in CHK_LVL. CHK_LVL may have additional bits set. 446* 447* The CL_TRACE macro must only be used after the CL_ENTRY macro as it 448* depends on that macro's implementation. 449* 450* If the DBG_LVL has the upper bit set, the output will contain 451* an "!ERROR!" statement between the function name and STRING. 452* 453* If the __MODULE__ preprocessor keyword is defined, that keyword will be 454* prepended to the function name, separated with a colon. 455* 456* In multi-processor environments where the current processor can be 457* determined, the zero-based number of the processor on which the output 458* is generated is prepended to the output. 459* 460* SEE ALSO 461* Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE_EXIT 462*********/ 463#define CL_TRACE( DBG_LVL, CHK_LVL, STRING ) \ 464{ \ 465switch( DBG_LVL & CL_DBG_ERROR ) \ 466{ \ 467 case CL_DBG_ERROR: \ 468 CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_ERROR ); \ 469 break; \ 470 default: \ 471 CL_PRINT( DBG_LVL, CHK_LVL, _CL_DBG_INFO ); \ 472 break; \ 473} \ 474CL_PRINT( DBG_LVL, CHK_LVL, STRING ); \ 475} 476 477/****d* Component Library: Debug Output/CL_TRACE_EXIT 478* NAME 479* CL_TRACE_EXIT 480* 481* DESCRIPTION 482* The CL_TRACE_EXIT macro combines the functionality of the CL_TRACE and 483* CL_EXIT macros, in that order. 484* 485* SYNOPSIS 486* CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING ); 487* 488* PARAMETERS 489* DBG_LVL 490* [in] Debug level for the string to output 491* 492* CHK_LVL 493* [in] Current debug level against which to check DBG_LVL 494* 495* STRING 496* [in] String to send to the current debug target. The string includes 497* parentheses in order to allow additional parameters. 498* 499* RETURN VALUE 500* This macro does not return a value. 501* 502* EXAMPLE 503* #define __MODULE__ "my_module" 504* #define MY_FUNC_DBG_LVL 1 505* 506* uint32_t my_dbg_lvl = CL_DBG_ALL; 507* 508* void 509* my_func() 510* { 511* CL_ENTER( MY_FUNC_DBG_LVL, my_dbg_lvl ); 512* CL_TRACE_EXIT( MY_FUNC_DBG_LVL, my_dbg_lvl, ("Hello %s!\n", "world") ); 513* } 514* 515* RESULT 516* my_module:my_func() [ 517* my_module:my_func(): Hello world! 518* my_module:my_func() ] 519* 520* NOTES 521* The requested string is printed only if all bits set in DBG_LVL are also 522* set in CHK_LVL. CHK_LVL may have additional bits set. 523* 524* The CL_TRACE_EXIT macro must only be used after the CL_ENTRY macro as it 525* depends on that macro's implementation. 526* 527* If the DBG_LVL has the upper bit set, the output will contain 528* an "!ERROR!" statement between the function name and STRING. 529* 530* If the __MODULE__ preprocessor keyword is defined, that keyword will be 531* prepended to the function name, separated with a colon. 532* 533* In multi-processor environments where the current processor can be 534* determined, the zero-based number of the processor on which the output 535* is generated is prepended to the output. 536* 537* SEE ALSO 538* Debug Output, Debug Levels, CL_PRINT, CL_ENTER, CL_EXIT, CL_TRACE 539*********/ 540#define CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING ) \ 541 CL_TRACE( DBG_LVL, CHK_LVL, STRING ); \ 542 CL_EXIT( DBG_LVL, CHK_LVL ); 543 544#else /* defined(_DEBUG_) */ 545 546/* Define as NULL macros in a free build. */ 547#define CL_PRINT( DBG_LVL, CHK_LVL, STRING ); 548#define CL_ENTER( DBG_LVL, CHK_LVL ); 549#define CL_EXIT( DBG_LVL, CHK_LVL ); 550#define CL_TRACE( DBG_LVL, CHK_LVL, STRING ); 551#define CL_TRACE_EXIT( DBG_LVL, CHK_LVL, STRING ); 552 553#endif /* defined(_DEBUG_) */ 554 555/****d* Component Library: Debug Output/64-bit Print Format 556* NAME 557* 64-bit Print Format 558* 559* DESCRIPTION 560* The 64-bit print keywords allow users to use 64-bit values in debug or 561* console output. 562* 563* Different platforms define 64-bit print formats differently. The 64-bit 564* print formats exposed by the component library are supported in all 565* platforms. 566* 567* VALUES 568* PRId64 569* Print a 64-bit integer in signed decimal format. 570* PRIx64 571* Print a 64-bit integer in hexadecimal format. 572* PRIo64 573* Print a 64-bit integer in octal format. 574* PRIu64 575* Print a 64-bit integer in unsigned decimal format. 576* 577* EXAMPLE 578* uint64 MyVal = 2; 579* // Print a 64-bit integer in hexadecimal format. 580* cl_dbg_out( "MyVal: 0x%" PRIx64 "\n", MyVal ); 581* 582* NOTES 583* Standard print flags to specify padding and precision can still be used 584* following the '%' sign in the string preceding the 64-bit print keyword. 585* 586* The above keywords are strings and make use of compilers' string 587* concatenation ability. 588*********/ 589void complib_init(void); 590 591void complib_exit(void); 592 593END_C_DECLS 594#endif /* _CL_DEBUG_H_ */ 595