contrib/ofed/management/opensm/include/complib/cl_debug.h

   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_ */