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 54 BEGIN_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 */ 90 boolean_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 */ 114 void 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 140 static 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 */ 156 void 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 { \ 465 switch( 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 } \ 474 CL_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 *********/ 589 void complib_init(void); 590 591 void complib_exit(void); 592 593 END_C_DECLS 594 #endif /* _CL_DEBUG_H_ */ 595