mDNSShared/DebugServices.h

   1 /* -*- Mode: C; tab-width: 4 -*-
   2  *
   3  * Copyright (c) 1997-2004 Apple Computer, Inc. All rights reserved.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 //---------------------------------------------------------------------------------------------------------------------------
  19 /*!     @header         DebugServices
  20
  21     Debugging Library
  22  */
  23
  24 #ifndef __DEBUG_SERVICES__
  25 #define __DEBUG_SERVICES__
  26
  27 #include    <stdarg.h>
  28
  29 #include    "CommonServices.h"
  30
  31 #if ( TARGET_OS_VXWORKS )
  32     #include    "logLib.h"
  33 #endif
  34
  35 #if 0
  36 #pragma mark == Settings ==
  37 #endif
  38
  39 //===========================================================================================================================
  40 //      Settings
  41 //===========================================================================================================================
  42
  43 // General
  44
  45 #if ( !defined( DEBUG ) )
  46     #define DEBUG       0
  47 #endif
  48
  49 #if ( defined( NDEBUG ) && DEBUG )
  50     #error NDEBUG defined and DEBUG is also enabled...they need to be in-sync
  51 #endif
  52
  53 // AssertMacros.h/Debugging.h overrides.
  54
  55 #if ( !defined( DEBUG_OVERRIDE_APPLE_MACROS ) )
  56     #define DEBUG_OVERRIDE_APPLE_MACROS     1
  57 #endif
  58
  59 // Routine name. Uses ISO __func__ where possible. Otherwise, uses the best thing that is available (if anything).
  60
  61 #if ( defined( __MWERKS__ ) || ( __GNUC__ > 2 ) || ( ( __GNUC__ == 2 ) && ( __GNUC_MINOR__ >= 9 ) ) )
  62     #define __ROUTINE__                 __func__
  63 #elif ( defined( __GNUC__ ) )
  64     #define __ROUTINE__                 __PRETTY_FUNCTION__
  65 #elif ( defined( _MSC_VER ) && !defined( _WIN32_WCE ) )
  66     #define __ROUTINE__                 __FUNCTION__
  67 #else
  68     #define __ROUTINE__                 ""
  69 #endif
  70
  71 // Variable argument macro support. Use ANSI C99 __VA_ARGS__ where possible. Otherwise, use the next best thing.
  72
  73 #if ( defined( __GNUC__ ) )
  74     #if ( ( __GNUC__ > 3 ) || ( ( __GNUC__ == 3 ) && ( __GNUC_MINOR__ >= 3) ) )
  75         #define DEBUG_C99_VA_ARGS       1
  76         #define DEBUG_GNU_VA_ARGS       0
  77     #else
  78         #define DEBUG_C99_VA_ARGS       0
  79         #define DEBUG_GNU_VA_ARGS       1
  80     #endif
  81 #elif ( defined( __MWERKS__ ) )
  82     #define DEBUG_C99_VA_ARGS           1
  83     #define DEBUG_GNU_VA_ARGS           0
  84 #else
  85     #define DEBUG_C99_VA_ARGS           0
  86     #define DEBUG_GNU_VA_ARGS           0
  87 #endif
  88
  89 #if 0
  90 #pragma mark == Output ==
  91 #endif
  92
  93 //---------------------------------------------------------------------------------------------------------------------------
  94 /*!     @defined        DEBUG_FPRINTF_ENABLED
  95
  96     @abstract   Enables ANSI C fprintf output.
  97  */
  98
  99 #if ( !defined( DEBUG_FPRINTF_ENABLED ) )
 100     #if ( !TARGET_API_MAC_OSX_KERNEL && !TARGET_OS_WINDOWS_CE )
 101         #define DEBUG_FPRINTF_ENABLED           1
 102     #else
 103         #define DEBUG_FPRINTF_ENABLED           0
 104     #endif
 105 #else
 106     #if ( TARGET_API_MAC_OSX_KERNEL || TARGET_OS_WINDOWS_CE )
 107         #error fprintf enabled, but not supported on Mac OS X kernel or Windows CE
 108     #endif
 109 #endif
 110
 111 //---------------------------------------------------------------------------------------------------------------------------
 112 /*!     @defined        DEBUG_MAC_OS_X_IOLOG_ENABLED
 113
 114     @abstract   Enables IOLog (Mac OS X Kernel) output.
 115  */
 116
 117 #if ( !defined( DEBUG_MAC_OS_X_IOLOG_ENABLED ) )
 118     #define DEBUG_MAC_OS_X_IOLOG_ENABLED        TARGET_API_MAC_OSX_KERNEL
 119 #endif
 120
 121 //---------------------------------------------------------------------------------------------------------------------------
 122 /*!     @defined        DEBUG_KPRINTF_ENABLED
 123
 124     @abstract   Enables kprintf (Mac OS X Kernel) output.
 125  */
 126
 127 #if ( !defined( DEBUG_KPRINTF_ENABLED ) )
 128     #define DEBUG_KPRINTF_ENABLED               TARGET_API_MAC_OSX_KERNEL
 129 #endif
 130
 131 //---------------------------------------------------------------------------------------------------------------------------
 132 /*!     @defined        DEBUG_IDEBUG_ENABLED
 133
 134     @abstract   Enables iDebug (Mac OS X user and Kernel) output.
 135
 136     @discussion
 137
 138     For Mac OS X kernel development, iDebug is enabled by default because we can dynamically check for the presence
 139     of iDebug via some exported IOKit symbols. Mac OS X app usage doesn't allow dynamic detection because it relies
 140     on statically linking to the iDebugServices.cp file so for Mac OS X app usage, you have to manually enable iDebug.
 141  */
 142
 143 #if ( !defined( DEBUG_IDEBUG_ENABLED ) )
 144     #define DEBUG_IDEBUG_ENABLED                TARGET_API_MAC_OSX_KERNEL
 145 #endif
 146
 147 //---------------------------------------------------------------------------------------------------------------------------
 148 /*!     @defined        DEBUG_CORE_SERVICE_ASSERTS_ENABLED
 149
 150     @abstract   Controls whether Core Services assert handling is enabled. Enabling requires CoreServices framework.
 151  */
 152
 153 #if ( !defined( DEBUG_CORE_SERVICE_ASSERTS_ENABLED ) )
 154     #if ( defined( __DEBUGGING__ ) )
 155         #define DEBUG_CORE_SERVICE_ASSERTS_ENABLED      1
 156     #else
 157         #define DEBUG_CORE_SERVICE_ASSERTS_ENABLED      0
 158     #endif
 159 #endif
 160
 161 //---------------------------------------------------------------------------------------------------------------------------
 162 /*!     @typedef        DebugOutputType
 163
 164     @abstract   Type of debug output (i.e. where the output goes).
 165  */
 166
 167 typedef uint32_t DebugOutputType;
 168
 169 #define kDebugOutputTypeNone                0x6E6F6E65U // 'none' - no params
 170 #define kDebugOutputTypeCustom              0x63757374U // 'cust' - 1st param = function ptr, 2nd param = context
 171 #define kDebugOutputTypeFPrintF             0x66707269U // 'fpri' - 1st param = DebugOutputTypeFlags [, 2nd param = filename]
 172 #define kDebugOutputTypeiDebug              0x69646267U // 'idbg' - no params
 173 #define kDebugOutputTypeKPrintF             0x6B707266U // 'kprf' - no params
 174 #define kDebugOutputTypeMacOSXIOLog         0x696C6F67U // 'ilog' - no params
 175 #define kDebugOutputTypeMacOSXLog           0x786C6F67U // 'xlog' - no params
 176 #define kDebugOutputTypeWindowsDebugger     0x77696E64U // 'wind' - no params
 177 #define kDebugOutputTypeWindowsEventLog     0x7765766CU // 'wevl' - 1st param = C-string name, 2nd param = HMODULE or NULL.
 178
 179 // Console meta output kind - Any kind of Console output (in horizontal order of preference):
 180 //
 181 // Mac OS X                     = ANSI printf (viewable in Console.app)
 182 // Mac OS X Kernel      = IOLog (/var/log/system.log) or kprintf (serial).
 183 // Windows                      = ANSI printf (Console window) or OutputDebugString (debugger).
 184 // Other                        = ANSI printf (viewer varies).
 185
 186 #define kDebugOutputTypeMetaConsole         0x434F4E53U // 'CONS' - no params
 187
 188 //---------------------------------------------------------------------------------------------------------------------------
 189 /*!     @typedef        DebugOutputTypeFlags
 190
 191     @abstract   Flags controlling how the output type is configured.
 192
 193     @constant   kDebugOutputTypeFlagsTypeMask   Bit mask for the output type (e.g. stdout, stderr, file, etc.).
 194     @constant   kDebugOutputTypeFlagsStdOut             fprintf should go to stdout.
 195     @constant   kDebugOutputTypeFlagsStdErr             fprintf should go to stderr.
 196     @constant   kDebugOutputTypeFlagsFile               fprintf should go to a specific file (filename passed as va_arg).
 197  */
 198
 199 typedef unsigned int DebugOutputTypeFlags;
 200
 201 #define kDebugOutputTypeFlagsTypeMask   0xF
 202 #define kDebugOutputTypeFlagsStdOut     1
 203 #define kDebugOutputTypeFlagsStdErr     2
 204 #define kDebugOutputTypeFlagsFile       10
 205
 206 //---------------------------------------------------------------------------------------------------------------------------
 207 /*!     @typedef        DebugOutputFunctionPtr
 208
 209     @abstract   Function ptr for a custom callback to print debug output.
 210  */
 211
 212 typedef void ( *DebugOutputFunctionPtr )( char *inData, size_t inSize, void *inContext );
 213
 214 //===========================================================================================================================
 215 //      Constants
 216 //===========================================================================================================================
 217
 218 #if 0
 219 #pragma mark == Flags ==
 220 #endif
 221
 222 //---------------------------------------------------------------------------------------------------------------------------
 223 /*!     @typedef        DebugFlags
 224
 225     @abstract   Flags controlling how output is printed.
 226  */
 227
 228 typedef uint32_t DebugFlags;
 229
 230 #define kDebugFlagsNone                 0
 231 #define kDebugFlagsNoAddress            ( 1 << 0 )
 232 #define kDebugFlagsNoOffset             ( 1 << 1 )
 233 #define kDebugFlags32BitOffset          ( 1 << 2 )
 234 #define kDebugFlagsNoASCII              ( 1 << 3 )
 235 #define kDebugFlagsNoNewLine            ( 1 << 4 )
 236 #define kDebugFlags8BitSeparator        ( 1 << 5 )
 237 #define kDebugFlags16BitSeparator       ( 1 << 6 )
 238 #define kDebugFlagsNo32BitSeparator     ( 1 << 7 )
 239 #define kDebugFlagsNo16ByteHexPad       ( 1 << 8 )
 240 #define kDebugFlagsNoByteCount          ( 1 << 9 )
 241
 242 //---------------------------------------------------------------------------------------------------------------------------
 243 /*!     @enum           DebugTaskLevelFlags
 244
 245     @abstract   Flags indicating the task level.
 246  */
 247
 248 enum
 249 {
 250     kDebugInterruptLevelShift               = 0,
 251     kDebugInterruptLevelMask                = 0x00000007,
 252     kDebugInVBLTaskMask                     = 0x00000010,
 253     kDebugInDeferredTaskMask                = 0x00000020,
 254     kDebugInSecondaryInterruptHandlerMask   = 0x00000040,
 255     kDebugPageFaultFatalMask                = 0x00000100,   // There should be a "kPageFaultFatalMask" in Debugging.h.
 256     kDebugMPTaskLevelMask                   = 0x00000200,   // There should be a "kMPTaskLevelMask" in Debugging.h.
 257     kDebugInterruptDepthShift               = 16,
 258     kDebugInterruptDepthMask                = 0x00FF0000
 259 };
 260
 261 #define DebugExtractTaskLevelInterruptLevel( LEVEL )    \
 262     ( ( ( LEVEL ) &kDebugInterruptLevelMask ) >> kDebugInterruptLevelShift )
 263
 264 #define DebugExtractTaskLevelInterruptDepth( LEVEL )    \
 265     ( ( ( LEVEL ) &kDebugInterruptDepthMask ) >> kDebugInterruptDepthShift )
 266
 267 #if 0
 268 #pragma mark == Levels ==
 269 #endif
 270
 271 //===========================================================================================================================
 272 //      Constants & Types - Levels
 273 //===========================================================================================================================
 274
 275 //---------------------------------------------------------------------------------------------------------------------------
 276 /*!     @typedef        DebugLevel
 277
 278     @abstract   Level used to control debug logging.
 279  */
 280
 281 typedef int32_t DebugLevel;
 282
 283 // Levels
 284
 285 #define kDebugLevelMask                 0x0000FFFF
 286 #define kDebugLevelChatty               100
 287 #define kDebugLevelVerbose              500
 288 #define kDebugLevelTrace                800
 289 #define kDebugLevelInfo                 1000
 290 #define kDebugLevelNotice               3000
 291 #define kDebugLevelWarning              5000
 292 #define kDebugLevelAssert               6000
 293 #define kDebugLevelRequire              7000
 294 #define kDebugLevelError                8000
 295 #define kDebugLevelCritical             9000
 296 #define kDebugLevelAlert                10000
 297 #define kDebugLevelEmergency            11000
 298 #define kDebugLevelTragic               12000
 299 #define kDebugLevelMax                  0x0000FFFF
 300
 301 // Level Flags
 302
 303 #define kDebugLevelFlagMask             0xFFFF0000
 304 #define kDebugLevelFlagStackTrace       0x00010000
 305 #define kDebugLevelFlagDebugBreak       0x00020000
 306
 307 //---------------------------------------------------------------------------------------------------------------------------
 308 /*!     @typedef        LogLevel
 309
 310     @abstract   Level used to control which events are logged.
 311  */
 312
 313 typedef int32_t LogLevel;
 314
 315 #define kLogLevelUninitialized      -1L
 316 #define kLogLevelAll                0L
 317 #define kLogLevelChatty             100L
 318 #define kLogLevelVerbose            500L
 319 #define kLogLevelTrace              800L
 320 #define kLogLevelInfo               1000L
 321 #define kLogLevelNotice             3000L
 322 #define kLogLevelWarning            4000L
 323 #define kLogLevelAssert             6000L
 324 #define kLogLevelRequire            7000L
 325 #define kLogLevelError              8000L
 326 #define kLogLevelCritical           9000L
 327 #define kLogLevelAlert              10000L
 328 #define kLogLevelEmergency          11000L
 329 #define kLogLevelTragic             12000L
 330 #define kLogLevelOff                0x0000FFFEL
 331
 332 #if 0
 333 #pragma mark == Properties ==
 334 #endif
 335
 336 //---------------------------------------------------------------------------------------------------------------------------
 337 /*!     @typedef        DebugPropertyTag
 338
 339     @abstract   Tag for properties.
 340  */
 341
 342 typedef uint32_t DebugPropertyTag;
 343
 344 #define kDebugPropertyTagPrintLevelMin      0x6D696E70U     // 'minp'   Get: 1st param = DebugLevel *
 345                                                             //                  Set: 1st param = DebugLevel
 346
 347 #define kDebugPropertyTagPrintLevel         kDebugPropertyTagPrintLevelMin
 348
 349 #define kDebugPropertyTagPrintLevelMax      0x706D786CU     // 'maxp'   Get: 1st param = DebugLevel *
 350                                                             //                  Set: 1st param = DebugLevel
 351
 352 #define kDebugPropertyTagBreakLevel         0x62726B6CU     // 'brkl'   Get: 1st param = DebugLevel *
 353                                                             //                  Set: 1st param = DebugLevel
 354 #if 0
 355 #pragma mark == General macros ==
 356 #endif
 357
 358 //---------------------------------------------------------------------------------------------------------------------------
 359 /*!     @defined        DEBUG_UNUSED
 360
 361     @abstract   Macro to mark a paramter as unused to avoid unused parameter warnings.
 362
 363     @discussion
 364
 365     There is no universally supported pragma/attribute for indicating a variable is unused. DEBUG_UNUSED lets us
 366     indicate a variable is unused in a manner that is supported by most compilers.
 367  */
 368
 369 #define DEBUG_UNUSED( X )           (void)( X )
 370
 371 //---------------------------------------------------------------------------------------------------------------------------
 372 /*!     @defined        DEBUG_USE_ONLY
 373
 374     @abstract   Macro to mark a variable as used only when debugging is enabled.
 375
 376     @discussion
 377
 378     Variables are sometimes needed only for debugging. When debugging is turned off, these debug-only variables generate
 379     compiler warnings about unused variables. To eliminate these warnings, use these macros to indicate variables that
 380     are only used for debugging.
 381  */
 382
 383 #if ( DEBUG )
 384     #define DEBUG_USE_ONLY( X )
 385 #else
 386     #define DEBUG_USE_ONLY( X )     (void)( X )
 387 #endif
 388
 389 //---------------------------------------------------------------------------------------------------------------------------
 390 /*!     @defined        DEBUG_LOCAL
 391
 392     @abstract   Macros to make variables and functions static when debugging is off, but extern when debugging is on.
 393
 394     @discussion
 395
 396     Rather than using "static" directly, using this macros allows you to access these variables external while
 397     debugging without being penalized for production builds.
 398  */
 399
 400 #if ( DEBUG )
 401     #define DEBUG_LOCAL
 402 #else
 403     #define DEBUG_LOCAL         static
 404 #endif
 405
 406 //---------------------------------------------------------------------------------------------------------------------------
 407 /*!     @defined        DEBUG_STATIC
 408
 409     @abstract   Macros to make variables and functions static when debugging is off, but extern when debugging is on.
 410
 411     @discussion
 412
 413     Rather than using "static" directly, using this macros allows you to access these variables external while
 414     debugging without being penalized for production builds.
 415  */
 416
 417 #if ( DEBUG )
 418     #define DEBUG_STATIC
 419 #else
 420     #define DEBUG_STATIC    static
 421 #endif
 422
 423 //---------------------------------------------------------------------------------------------------------------------------
 424 /*!     @defined        DEBUG_EXPORT
 425
 426     @abstract   Macros to export variables.
 427
 428     @discussion
 429
 430     "__private_extern__" is a hack for IOKit to allow symbols to be exported from compilation units, but
 431     // not exported outside a driver (IOKit uses a lame global namespace for symbols). This still does not
 432     // solve the problem of multiple drivers in the same dependency chain since they share symbols.
 433  */
 434
 435 #if ( TARGET_API_MAC_OSX_KERNEL )
 436     #define DEBUG_EXPORT        __private_extern__
 437 #else
 438     #define DEBUG_EXPORT        extern
 439 #endif
 440
 441 //---------------------------------------------------------------------------------------------------------------------------
 442 /*!     @defined        debug_add
 443
 444     @abstract   Macro to add (or subtract if negative) a value when debugging is on. Does nothing if debugging is off.
 445  */
 446
 447 #if ( DEBUG )
 448     #define debug_add( A, B )       ( A ) += ( B )
 449 #else
 450     #define debug_add( A, B )
 451 #endif
 452
 453 //---------------------------------------------------------------------------------------------------------------------------
 454 /*!     @defined        debug_perform
 455
 456     @abstract   Macro to perform something in debug-only builds.
 457  */
 458
 459 #if ( DEBUG )
 460     #define debug_perform( X )      do { X; } while( 0 )
 461 #else
 462     #define debug_perform( X )
 463 #endif
 464
 465 //---------------------------------------------------------------------------------------------------------------------------
 466 /*!     @function       translate_errno
 467
 468     @abstract   Returns 0 if the test success. If the test fails, returns errno if non-zero and othewise the alternate error.
 469  */
 470
 471 #define translate_errno( TEST, ERRNO, ALTERNATE_ERROR )     ( ( TEST ) ? 0 : ( ERRNO ) ? ( ERRNO ) : ( ALTERNATE_ERROR ) )
 472
 473 #if 0
 474 #pragma mark == Compile Time macros ==
 475 #endif
 476
 477 //---------------------------------------------------------------------------------------------------------------------------
 478 /*!     @defined        check_compile_time
 479
 480     @abstract   Performs a compile-time check of something such as the size of an int.
 481
 482     @discussion
 483
 484     This declares an array with a size that is determined by a compile-time expression. If the expression evaluates
 485     to 0, the array has a size of -1, which is illegal and generates a compile-time error.
 486
 487     For example:
 488
 489     check_compile_time( sizeof( int ) == 4 );
 490
 491     Note: This only works with compile-time expressions.
 492     Note: This only works in places where extern declarations are allowed (e.g. global scope).
 493
 494     References:
 495
 496     <http://www.jaggersoft.com/pubs/CVu11_3.html>
 497     <http://www.jaggersoft.com/pubs/CVu11_5.html>
 498
 499     Note: The following macros differ from the macros on the www.jaggersoft.com web site because those versions do not
 500     work with GCC due to GCC allow a zero-length array. Using a -1 condition turned out to be more portable.
 501  */
 502
 503 #define check_compile_time( X )     extern int debug_compile_time_name[ ( X ) ? 1 : -1 ]
 504
 505 //---------------------------------------------------------------------------------------------------------------------------
 506 /*!     @defined        check_compile_time_code
 507
 508     @abstract   Perform a compile-time check, suitable for placement in code, of something such as the size of an int.
 509
 510     @discussion
 511
 512     This creates a switch statement with an existing case for 0 and an additional case using the result of a
 513     compile-time expression. A switch statement cannot have two case labels with the same constant so if the
 514     compile-time expression evaluates to 0, it is illegal and generates a compile-time error. If the compile-time
 515     expression does not evaluate to 0, the resulting value is used as the case label and it compiles without error.
 516
 517     For example:
 518
 519     check_compile_time_code( sizeof( int ) == 4 );
 520
 521     Note: This only works with compile-time expressions.
 522     Note: This does not work in a global scope so it must be inside a function.
 523
 524     References:
 525
 526     <http://www.jaggersoft.com/pubs/CVu11_3.html>
 527     <http://www.jaggersoft.com/pubs/CVu11_5.html>
 528  */
 529
 530 #define check_compile_time_code( X )    switch( 0 ) { case 0: case X:; }
 531
 532 #if 0
 533 #pragma mark == check macros ==
 534 #endif
 535
 536 //---------------------------------------------------------------------------------------------------------------------------
 537 /*!     @defined        check
 538
 539     @abstract   Check that an expression is true (non-zero).
 540
 541     @discussion
 542
 543     If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
 544     function name, etc.) using the default debugging output method.
 545
 546     Code inside check() statements is not compiled into production builds.
 547  */
 548
 549 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 550     #undef check
 551 #endif
 552 #if ( !defined( check ) )
 553     #if ( DEBUG )
 554         #define check( X )                                                                                  \
 555     do                                                                                              \
 556     {                                                                                               \
 557         if( !( X ) )                                                                                \
 558         {                                                                                           \
 559             debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ );                     \
 560         }                                                                                           \
 561     } while( 0 )
 562     #else
 563         #define check( X )
 564     #endif
 565 #endif
 566
 567 //---------------------------------------------------------------------------------------------------------------------------
 568 /*!     @defined        check_string
 569
 570     @abstract   Check that an expression is true (non-zero) with an explanation.
 571
 572     @discussion
 573
 574     If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
 575     function name, etc.) and a custom explanation string using the default debugging output method.
 576
 577     Code inside check_string() statements is not compiled into production builds.
 578  */
 579
 580 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 581     #undef check_string
 582 #endif
 583 #if ( !defined( check_string ) )
 584     #if ( DEBUG )
 585         #define check_string( X, STR )                                                                      \
 586     do                                                                                              \
 587     {                                                                                               \
 588         if( !( X ) )                                                                                \
 589         {                                                                                           \
 590             debug_print_assert( 0, # X, STR, __FILE__, __LINE__, __ROUTINE__ );                      \
 591         }                                                                                           \
 592                                                                                                             \
 593     }   while( 0 )
 594     #else
 595         #define check_string( X, STR )
 596     #endif
 597 #endif
 598
 599 //---------------------------------------------------------------------------------------------------------------------------
 600 /*!     @defined        check_noerr
 601
 602     @abstract   Check that an error code is noErr (0).
 603
 604     @discussion
 605
 606     If the error code is non-0, this prints debugging information (actual expression string, file, line number,
 607     function name, etc.) using the default debugging output method.
 608
 609     Code inside check_noerr() statements is not compiled into production builds.
 610  */
 611
 612 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 613     #undef check_noerr
 614 #endif
 615 #if ( !defined( check_noerr ) )
 616     #if ( DEBUG )
 617         #define check_noerr( ERR )                                                                          \
 618     do                                                                                              \
 619     {                                                                                               \
 620         int_least32_t localErr;                                                               \
 621                                                                                                             \
 622         localErr = (int_least32_t)( ERR );                                                          \
 623         if( localErr != 0 )                                                                         \
 624         {                                                                                           \
 625             debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ );            \
 626         }                                                                                           \
 627                                                                                                             \
 628     }   while( 0 )
 629     #else
 630         #define check_noerr( ERR )
 631     #endif
 632 #endif
 633
 634 //---------------------------------------------------------------------------------------------------------------------------
 635 /*!     @defined        check_noerr_string
 636
 637     @abstract   Check that an error code is noErr (0) with an explanation.
 638
 639     @discussion
 640
 641     If the error code is non-0, this prints debugging information (actual expression string, file, line number,
 642     function name, etc.) and a custom explanation string using the default debugging output method.
 643
 644     Code inside check_noerr_string() statements is not compiled into production builds.
 645  */
 646
 647 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 648     #undef check_noerr_string
 649 #endif
 650 #if ( !defined( check_noerr_string ) )
 651     #if ( DEBUG )
 652         #define check_noerr_string( ERR, STR )                                                              \
 653     do                                                                                              \
 654     {                                                                                               \
 655         int_least32_t localErr;                                                               \
 656                                                                                                             \
 657         localErr = (int_least32_t)( ERR );                                                          \
 658         if( localErr != 0 )                                                                         \
 659         {                                                                                           \
 660             debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ );             \
 661         }                                                                                           \
 662                                                                                                             \
 663     }   while( 0 )
 664     #else
 665         #define check_noerr_string( ERR, STR )
 666     #endif
 667 #endif
 668
 669 //---------------------------------------------------------------------------------------------------------------------------
 670 /*!     @defined        check_translated_errno
 671
 672     @abstract   Check a condition and prints errno (if non-zero) to the log.
 673
 674     @discussion
 675
 676     Code inside check_translated_errno() statements is not compiled into production builds.
 677  */
 678
 679 #if ( !defined( check_translated_errno ) )
 680     #if ( DEBUG )
 681         #define check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR )                                      \
 682     do                                                                                              \
 683     {                                                                                               \
 684         if( !( TEST ) )                                                                             \
 685         {                                                                                           \
 686             int_least32_t localErr;                                                           \
 687                                                                                                             \
 688             localErr = (int_least32_t)( ERRNO );                                                    \
 689             localErr = ( localErr != 0 ) ? localErr : (int_least32_t)( ALTERNATE_ERROR );           \
 690             debug_print_assert( localErr, # TEST, NULL, __FILE__, __LINE__, __ROUTINE__ );           \
 691         }                                                                                           \
 692                                                                                                             \
 693     }   while( 0 )
 694     #else
 695         #define check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR )
 696     #endif
 697 #endif
 698
 699 //---------------------------------------------------------------------------------------------------------------------------
 700 /*!     @defined        check_ptr_overlap
 701
 702     @abstract   Checks that two ptrs do not overlap.
 703  */
 704
 705 #define check_ptr_overlap( P1, P1_SIZE, P2, P2_SIZE )                                       \
 706     do                                                                                      \
 707     {                                                                                       \
 708         check( !( ( (uintptr_t)( P1 ) >=     (uintptr_t)( P2 ) ) &&                         \
 709                   ( (uintptr_t)( P1 ) <  ( ( (uintptr_t)( P2 ) ) + ( P2_SIZE ) ) ) ) );     \
 710         check( !( ( (uintptr_t)( P2 ) >=     (uintptr_t)( P1 ) ) &&                         \
 711                   ( (uintptr_t)( P2 ) <  ( ( (uintptr_t)( P1 ) ) + ( P1_SIZE ) ) ) ) );     \
 712                                                                                             \
 713     }   while( 0 )
 714
 715 #if 0
 716 #pragma mark == require macros ==
 717 #endif
 718
 719 //---------------------------------------------------------------------------------------------------------------------------
 720 /*!     @defined        require
 721
 722     @abstract   Requires that an expression evaluate to true.
 723
 724     @discussion
 725
 726     If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
 727     function name, etc.) using the default debugging output method then jumps to a label.
 728  */
 729
 730 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 731     #undef require
 732 #endif
 733 #if ( !defined( require ) )
 734     #define require( X, LABEL )                                                                             \
 735     do                                                                                                  \
 736     {                                                                                                   \
 737         if( !( X ) )                                                                                    \
 738         {                                                                                               \
 739             debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ );                         \
 740             goto LABEL;                                                                                 \
 741         }                                                                                               \
 742                                                                                                             \
 743     }   while( 0 )
 744 #endif
 745
 746 //---------------------------------------------------------------------------------------------------------------------------
 747 /*!     @defined        require_string
 748
 749     @abstract   Requires that an expression evaluate to true with an explanation.
 750
 751     @discussion
 752
 753     If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
 754     function name, etc.) and a custom explanation string using the default debugging output method then jumps to a label.
 755  */
 756
 757 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 758     #undef require_string
 759 #endif
 760 #if ( !defined( require_string ) )
 761     #define require_string( X, LABEL, STR )                                                                 \
 762     do                                                                                                  \
 763     {                                                                                                   \
 764         if( !( X ) )                                                                                    \
 765         {                                                                                               \
 766             debug_print_assert( 0, # X, STR, __FILE__, __LINE__, __ROUTINE__ );                          \
 767             goto LABEL;                                                                                 \
 768         }                                                                                               \
 769                                                                                                             \
 770     }   while( 0 )
 771 #endif
 772
 773 //---------------------------------------------------------------------------------------------------------------------------
 774 /*!     @defined        require_quiet
 775
 776     @abstract   Requires that an expression evaluate to true.
 777
 778     @discussion
 779
 780     If expression evalulates to false, this jumps to a label. No debugging information is printed.
 781  */
 782
 783 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 784     #undef require_quiet
 785 #endif
 786 #if ( !defined( require_quiet ) )
 787     #define require_quiet( X, LABEL )                                                                       \
 788     do                                                                                                  \
 789     {                                                                                                   \
 790         if( !( X ) )                                                                                    \
 791         {                                                                                               \
 792             goto LABEL;                                                                                 \
 793         }                                                                                               \
 794                                                                                                             \
 795     }   while( 0 )
 796 #endif
 797
 798 //---------------------------------------------------------------------------------------------------------------------------
 799 /*!     @defined        require_noerr
 800
 801     @abstract   Require that an error code is noErr (0).
 802
 803     @discussion
 804
 805     If the error code is non-0, this prints debugging information (actual expression string, file, line number,
 806     function name, etc.) using the default debugging output method then jumps to a label.
 807  */
 808
 809 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 810     #undef require_noerr
 811 #endif
 812 #if ( !defined( require_noerr ) )
 813     #define require_noerr( ERR, LABEL )                                                                     \
 814     do                                                                                                  \
 815     {                                                                                                   \
 816         int_least32_t localErr;                                                                   \
 817                                                                                                             \
 818         localErr = (int_least32_t)( ERR );                                                              \
 819         if( localErr != 0 )                                                                             \
 820         {                                                                                               \
 821             debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ );                \
 822             goto LABEL;                                                                                 \
 823         }                                                                                               \
 824                                                                                                             \
 825     }   while( 0 )
 826 #endif
 827
 828 //---------------------------------------------------------------------------------------------------------------------------
 829 /*!     @defined        require_noerr_string
 830
 831     @abstract   Require that an error code is noErr (0).
 832
 833     @discussion
 834
 835     If the error code is non-0, this prints debugging information (actual expression string, file, line number,
 836     function name, etc.), and a custom explanation string using the default debugging output method using the
 837     default debugging output method then jumps to a label.
 838  */
 839
 840 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 841     #undef require_noerr_string
 842 #endif
 843 #if ( !defined( require_noerr_string ) )
 844     #define require_noerr_string( ERR, LABEL, STR )                                                         \
 845     do                                                                                                  \
 846     {                                                                                                   \
 847         int_least32_t localErr;                                                                   \
 848                                                                                                             \
 849         localErr = (int_least32_t)( ERR );                                                              \
 850         if( localErr != 0 )                                                                             \
 851         {                                                                                               \
 852             debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ );                 \
 853             goto LABEL;                                                                                 \
 854         }                                                                                               \
 855                                                                                                             \
 856     }   while( 0 )
 857 #endif
 858
 859 //---------------------------------------------------------------------------------------------------------------------------
 860 /*!     @defined        require_noerr_action_string
 861
 862     @abstract   Require that an error code is noErr (0).
 863
 864     @discussion
 865
 866     If the error code is non-0, this prints debugging information (actual expression string, file, line number,
 867     function name, etc.), and a custom explanation string using the default debugging output method using the
 868     default debugging output method then executes an action and jumps to a label.
 869  */
 870
 871 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 872     #undef require_noerr_action_string
 873 #endif
 874 #if ( !defined( require_noerr_action_string ) )
 875     #define require_noerr_action_string( ERR, LABEL, ACTION, STR )                                          \
 876     do                                                                                                  \
 877     {                                                                                                   \
 878         int_least32_t localErr;                                                                   \
 879                                                                                                             \
 880         localErr = (int_least32_t)( ERR );                                                              \
 881         if( localErr != 0 )                                                                             \
 882         {                                                                                               \
 883             debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ );                 \
 884             { ACTION; }                                                                                 \
 885             goto LABEL;                                                                                 \
 886         }                                                                                               \
 887                                                                                                             \
 888     }   while( 0 )
 889 #endif
 890
 891 //---------------------------------------------------------------------------------------------------------------------------
 892 /*!     @defined        require_noerr_quiet
 893
 894     @abstract   Require that an error code is noErr (0).
 895
 896     @discussion
 897
 898     If the error code is non-0, this jumps to a label. No debugging information is printed.
 899  */
 900
 901 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 902     #undef require_noerr_quiet
 903 #endif
 904 #if ( !defined( require_noerr_quiet ) )
 905     #define require_noerr_quiet( ERR, LABEL )                                                               \
 906     do                                                                                                  \
 907     {                                                                                                   \
 908         if( ( ERR ) != 0 )                                                                              \
 909         {                                                                                               \
 910             goto LABEL;                                                                                 \
 911         }                                                                                               \
 912                                                                                                             \
 913     }   while( 0 )
 914 #endif
 915
 916 //---------------------------------------------------------------------------------------------------------------------------
 917 /*!     @defined        require_noerr_action
 918
 919     @abstract   Require that an error code is noErr (0) with an action to execute otherwise.
 920
 921     @discussion
 922
 923     If the error code is non-0, this prints debugging information (actual expression string, file, line number,
 924     function name, etc.) using the default debugging output method then executes an action and jumps to a label.
 925  */
 926
 927 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 928     #undef require_noerr_action
 929 #endif
 930 #if ( !defined( require_noerr_action ) )
 931     #define require_noerr_action( ERR, LABEL, ACTION )                                                      \
 932     do                                                                                                  \
 933     {                                                                                                   \
 934         int_least32_t localErr;                                                                   \
 935                                                                                                             \
 936         localErr = (int_least32_t)( ERR );                                                              \
 937         if( localErr != 0 )                                                                             \
 938         {                                                                                               \
 939             debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ );                \
 940             { ACTION; }                                                                                 \
 941             goto LABEL;                                                                                 \
 942         }                                                                                               \
 943                                                                                                             \
 944     }   while( 0 )
 945 #endif
 946
 947 //---------------------------------------------------------------------------------------------------------------------------
 948 /*!     @defined        require_noerr_action_quiet
 949
 950     @abstract   Require that an error code is noErr (0) with an action to execute otherwise.
 951
 952     @discussion
 953
 954     If the error code is non-0, this executes an action and jumps to a label. No debugging information is printed.
 955  */
 956
 957 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 958     #undef require_noerr_action_quiet
 959 #endif
 960 #if ( !defined( require_noerr_action_quiet ) )
 961     #define require_noerr_action_quiet( ERR, LABEL, ACTION )                                                \
 962     do                                                                                                  \
 963     {                                                                                                   \
 964         if( ( ERR ) != 0 )                                                                              \
 965         {                                                                                               \
 966             { ACTION; }                                                                                 \
 967             goto LABEL;                                                                                 \
 968         }                                                                                               \
 969                                                                                                             \
 970     }   while( 0 )
 971 #endif
 972
 973 //---------------------------------------------------------------------------------------------------------------------------
 974 /*!     @defined        require_action
 975
 976     @abstract   Requires that an expression evaluate to true with an action to execute otherwise.
 977
 978     @discussion
 979
 980     If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
 981     function name, etc.) using the default debugging output method then executes an action and jumps to a label.
 982  */
 983
 984 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
 985     #undef require_action
 986 #endif
 987 #if ( !defined( require_action ) )
 988     #define require_action( X, LABEL, ACTION )                                                              \
 989     do                                                                                                  \
 990     {                                                                                                   \
 991         if( !( X ) )                                                                                    \
 992         {                                                                                               \
 993             debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ );                         \
 994             { ACTION; }                                                                                 \
 995             goto LABEL;                                                                                 \
 996         }                                                                                               \
 997                                                                                                             \
 998     }   while( 0 )
 999 #endif
1000
1001 //---------------------------------------------------------------------------------------------------------------------------
1002 /*!     @defined        require_action_quiet
1003
1004     @abstract   Requires that an expression evaluate to true with an action to execute otherwise.
1005
1006     @discussion
1007
1008     If expression evalulates to false, this executes an action and jumps to a label. No debugging information is printed.
1009  */
1010
1011 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
1012     #undef require_action_quiet
1013 #endif
1014 #if ( !defined( require_action_quiet ) )
1015     #define require_action_quiet( X, LABEL, ACTION )                                                        \
1016     do                                                                                                  \
1017     {                                                                                                   \
1018         if( !( X ) )                                                                                    \
1019         {                                                                                               \
1020             { ACTION; }                                                                                 \
1021             goto LABEL;                                                                                 \
1022         }                                                                                               \
1023                                                                                                             \
1024     }   while( 0 )
1025 #endif
1026
1027 //---------------------------------------------------------------------------------------------------------------------------
1028 /*!     @defined        require_action_string
1029
1030     @abstract   Requires that an expression evaluate to true with an explanation and action to execute otherwise.
1031
1032     @discussion
1033
1034     If expression evalulates to false, this prints debugging information (actual expression string, file, line number,
1035     function name, etc.) and a custom explanation string using the default debugging output method then executes an
1036     action and jumps to a label.
1037  */
1038
1039 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
1040     #undef require_action_string
1041 #endif
1042 #if ( !defined( require_action_string ) )
1043     #define require_action_string( X, LABEL, ACTION, STR )                                                  \
1044     do                                                                                                  \
1045     {                                                                                                   \
1046         if( !( X ) )                                                                                    \
1047         {                                                                                               \
1048             debug_print_assert( 0, # X, STR, __FILE__, __LINE__, __ROUTINE__ );                      \
1049             { ACTION; }                                                                                 \
1050             goto LABEL;                                                                                 \
1051         }                                                                                               \
1052                                                                                                             \
1053     }   while( 0 )
1054
1055 #endif
1056
1057 //---------------------------------------------------------------------------------------------------------------------------
1058 /*!     @defined        require_throw
1059
1060     @abstract   Requires that an expression evaluates to true or an exception is thrown.
1061
1062     @discussion
1063
1064     If the expression evaluates to false, this prints debugging information (actual expression string, file,
1065     line number, function name, etc.) using the default debugging output method then throws an exception.
1066  */
1067
1068 #if ( defined( __cplusplus ) )
1069     #define require_throw( X )                                                                              \
1070     do                                                                                                  \
1071     {                                                                                                   \
1072         if( !( X ) )                                                                                    \
1073         {                                                                                               \
1074             debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ );                         \
1075             throw kUnknownErr;                                                                          \
1076         }                                                                                               \
1077                                                                                                             \
1078     }   while( 0 )
1079 #endif
1080
1081 #if 0
1082 #pragma mark == Design-By-Contract macros ==
1083 #endif
1084
1085 //===========================================================================================================================
1086 //      Design-By-Contract macros
1087 //===========================================================================================================================
1088
1089 #define ensure( X )                                                 check( X )
1090 #define ensure_string( X, STR )                                     check_string( X, STR )
1091 #define ensure_noerr( ERR )                                         check_noerr( ERR )
1092 #define ensure_noerr_string( ERR, STR )                             check_noerr_string( ERR, STR )
1093 #define ensure_translated_errno( TEST, ERRNO, ALTERNATE_ERROR )     check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR )
1094
1095 // Note: Design-By-Contract "require" macros are already defined elsewhere.
1096
1097 #if 0
1098 #pragma mark == Expect macros ==
1099 #endif
1100
1101 //===========================================================================================================================
1102 //      Expect macros
1103 //===========================================================================================================================
1104
1105 // Expect macros allow code to include runtime checking of things that should not happen in shipping code (e.g. internal
1106 // programmer errors, such as a NULL parameter where it is not allowed). Once the code has been verified to work correctly
1107 // without asserting, the DEBUG_EXPECT_VERIFIED conditional can be set to eliminate the error checking entirely. It can
1108 // also be useful to measure the cost of error checking code by profiling with it enable and with it disabled.
1109
1110 #if ( DEBUG_EXPECT_VERIFIED )
1111     #define require_expect
1112     #define require_string_expect
1113     #define require_quiet_expect
1114     #define require_noerr_expect
1115     #define require_noerr_string_expect
1116     #define require_noerr_action_string_expect
1117     #define require_noerr_quiet_expect
1118     #define require_noerr_action_expect
1119     #define require_noerr_action_quiet_expect
1120     #define require_action_expect
1121     #define require_action_quiet_expect
1122     #define require_action_string_expect
1123 #else
1124     #define require_expect                          require
1125     #define require_string_expect                   require_string
1126     #define require_quiet_expect                    require_quiet
1127     #define require_noerr_expect                    require_noerr
1128     #define require_noerr_string_expect             require_noerr_string
1129     #define require_noerr_action_string_expect      require_noerr_action_string
1130     #define require_noerr_quiet_expect              require_noerr_quiet
1131     #define require_noerr_action_expect             require_noerr_action
1132     #define require_noerr_action_quiet_expect       require_noerr_action_quiet
1133     #define require_action_expect                   require_action
1134     #define require_action_quiet_expect             require_action_quiet
1135     #define require_action_string_expect            require_action_string
1136 #endif
1137
1138 #if 0
1139 #pragma mark == Output macros ==
1140 #endif
1141
1142 //---------------------------------------------------------------------------------------------------------------------------
1143 /*!     @defined        debug_string
1144
1145     @abstract   Prints a debugging C string.
1146  */
1147
1148 #if ( DEBUG_OVERRIDE_APPLE_MACROS )
1149     #undef debug_string
1150 #endif
1151 #if ( !defined( debug_string ) )
1152     #if ( DEBUG )
1153         #define debug_string( STR )                                                                     \
1154     do                                                                                          \
1155     {                                                                                           \
1156         debug_print_assert( 0, NULL, STR, __FILE__, __LINE__, __ROUTINE__ );                    \
1157                                                                                                         \
1158     }   while( 0 )
1159     #else
1160         #define debug_string( STR )
1161     #endif
1162 #endif
1163
1164 //---------------------------------------------------------------------------------------------------------------------------
1165 /*!     @defined        debug_print_assert
1166
1167     @abstract   Prints an assertion.
1168  */
1169
1170 #if ( DEBUG )
1171     #define debug_print_assert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION )   \
1172     DebugPrintAssert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION )
1173 #else
1174     #define debug_print_assert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION )
1175 #endif
1176
1177 //---------------------------------------------------------------------------------------------------------------------------
1178 /*!     @defined        dlog
1179
1180     @abstract   Prints a debug-only message.
1181  */
1182
1183 #if ( DEBUG )
1184     #if ( DEBUG_C99_VA_ARGS )
1185         #define dlog(... )         DebugPrintF( __VA_ARGS__ )
1186     #elif ( DEBUG_GNU_VA_ARGS )
1187         #define dlog( ARGS... )     DebugPrintF( ## ARGS )
1188     #else
1189         #define dlog                DebugPrintF
1190     #endif
1191 #else
1192     #if ( DEBUG_C99_VA_ARGS )
1193         #define dlog(... )
1194     #elif ( DEBUG_GNU_VA_ARGS )
1195         #define dlog( ARGS... )
1196     #else
1197         #define dlog                while( 0 )
1198     #endif
1199 #endif
1200
1201 //---------------------------------------------------------------------------------------------------------------------------
1202 /*!     @defined        dlogv
1203
1204     @abstract   Prints a debug-only message.
1205  */
1206
1207 #if ( DEBUG )
1208     #define dlogv( LEVEL, FORMAT, LIST )        DebugPrintFVAList( ( LEVEL ), ( FORMAT ), ( LIST ) )
1209 #else
1210     #define dlogv( LEVEL, FORMAT, LIST )
1211 #endif
1212
1213 //---------------------------------------------------------------------------------------------------------------------------
1214 /*!     @defined        dlogmem
1215
1216     @abstract   Prints a debug-only dump of memory.
1217  */
1218
1219 #if ( DEBUG )
1220     #define dlogmem( LEVEL, PTR, SIZE )     \
1221     DebugHexDump( ( LEVEL ), 0, NULL, 0, 0, NULL, 0, ( PTR ), ( PTR ), ( SIZE ), kDebugFlagsNone, NULL, 0 )
1222 #else
1223     #define dlogmem( LEVEL, PTR, SIZE )
1224 #endif
1225
1226 //---------------------------------------------------------------------------------------------------------------------------
1227 /*!     @defined        DebugNSLog
1228
1229     @abstract   Debug-only macro for the Cocoa NSLog function.
1230  */
1231
1232 #if ( DEBUG )
1233     #if ( DEBUG_C99_VA_ARGS )
1234         #define DebugNSLog(... )           NSLog( __VA_ARGS__ )
1235     #elif ( DEBUG_GNU_VA_ARGS )
1236         #define DebugNSLog( ARGS... )       NSLog( ## ARGS )
1237     #else
1238         #define DebugNSLog                  NSLog
1239     #endif
1240 #else
1241     #if ( DEBUG_C99_VA_ARGS )
1242         #define DebugNSLog(... )
1243     #elif ( DEBUG_GNU_VA_ARGS )
1244         #define DebugNSLog( ARGS... )
1245     #else
1246         #define DebugNSLog                  while( 0 )
1247     #endif
1248 #endif
1249
1250 //---------------------------------------------------------------------------------------------------------------------------
1251 /*!     @defined        DebugLogMsg
1252
1253     @abstract   Debug-only macro for the VxWorks logMsg function.
1254  */
1255
1256 #if ( TARGET_OS_VXWORKS )
1257     #if ( DEBUG )
1258         #define DebugLogMsg( LEVEL, FORMAT, P1, P2, P3, P4, P5, P6 )                            \
1259     do                                                                                  \
1260     {                                                                                   \
1261         if( ( inLevel >= gDebugPrintLevelMin ) || ( inLevel <= gDebugPrintLevelMax ) )  \
1262         {                                                                               \
1263             logMsg( ( FORMAT ), ( P1 ), ( P2 ), ( P3 ), ( P4 ), ( P5 ), ( P6 ) );       \
1264         }                                                                               \
1265                                                                                                 \
1266     }   while( 0 )
1267     #else
1268         #define DebugLogMsg( LEVEL, FORMAT, P1, P2, P3, P4, P5, P6 )
1269     #endif
1270 #else
1271     #define DebugLogMsg     dlog
1272 #endif
1273
1274 #if 0
1275 #pragma mark == Routines - General ==
1276 #endif
1277
1278 #ifdef  __cplusplus
1279 extern "C" {
1280 #endif
1281
1282 //---------------------------------------------------------------------------------------------------------------------------
1283 /*!     @function       DebugInitialize
1284
1285     @abstract   Initializes the debugging library for a specific kind of output.
1286
1287     @param              inType
1288     @param              varArg          Variable number parameters, controlled by the "inType" parameter.
1289  */
1290
1291 #if ( DEBUG )
1292 DEBUG_EXPORT OSStatus   DebugInitialize( DebugOutputType inType, ... );
1293 #endif
1294
1295 #if ( DEBUG )
1296     #if ( DEBUG_C99_VA_ARGS )
1297         #define debug_initialize(... )         DebugInitialize( __VA_ARGS__ )
1298     #elif ( DEBUG_GNU_VA_ARGS )
1299         #define debug_initialize( ARGS... )     DebugInitialize( ## ARGS )
1300     #else
1301         #define debug_initialize                DebugInitialize
1302     #endif
1303 #else
1304     #if ( DEBUG_C99_VA_ARGS )
1305         #define debug_initialize(... )
1306     #elif ( DEBUG_GNU_VA_ARGS )
1307         #define debug_initialize( ARGS... )
1308     #else
1309         #define debug_initialize                while( 0 )
1310     #endif
1311 #endif
1312
1313 //---------------------------------------------------------------------------------------------------------------------------
1314 /*!     @function       DebugFinalize
1315
1316     @abstract   Releases any resources used by the debugging library
1317  */
1318
1319 #if ( DEBUG )
1320 DEBUG_EXPORT void       DebugFinalize( void );
1321 #endif
1322
1323 #if ( DEBUG )
1324     #define debug_terminate()   DebugFinalize()
1325 #else
1326     #define debug_terminate()
1327 #endif
1328
1329 //---------------------------------------------------------------------------------------------------------------------------
1330 /*!     @function       DebugGetProperty
1331
1332     @abstract   Gets the specified property from the debugging library.
1333  */
1334
1335 #if ( DEBUG )
1336 DEBUG_EXPORT OSStatus   DebugGetProperty( DebugPropertyTag inTag, ... );
1337 #endif
1338
1339 #if ( DEBUG )
1340     #if ( DEBUG_C99_VA_ARGS )
1341         #define debug_get_property(... )           DebugGetProperty( __VA_ARGS__ )
1342     #elif ( DEBUG_GNU_VA_ARGS )
1343         #define debug_get_property( ARGS... )       DebugGetProperty( ## ARGS )
1344     #else
1345         #define debug_get_property                  DebugGetProperty
1346     #endif
1347 #else
1348     #if ( DEBUG_C99_VA_ARGS )
1349         #define debug_get_property(... )
1350     #elif ( DEBUG_GNU_VA_ARGS )
1351         #define debug_get_property( ARGS... )
1352     #else
1353         #define debug_get_property                  while( 0 )
1354     #endif
1355 #endif
1356
1357 //---------------------------------------------------------------------------------------------------------------------------
1358 /*!     @function       DebugSetProperty
1359
1360     @abstract   Sets the specified property from the debugging library.
1361  */
1362
1363 #if ( DEBUG )
1364 DEBUG_EXPORT OSStatus   DebugSetProperty( DebugPropertyTag inTag, ... );
1365 #endif
1366
1367 #if ( DEBUG )
1368     #if ( DEBUG_C99_VA_ARGS )
1369         #define debug_set_property(... )           DebugSetProperty( __VA_ARGS__ )
1370     #elif ( DEBUG_GNU_VA_ARGS )
1371         #define debug_set_property( ARGS... )       DebugSetProperty( ## ARGS )
1372     #else
1373         #define debug_set_property                  DebugSetProperty
1374     #endif
1375 #else
1376     #if ( DEBUG_C99_VA_ARGS )
1377         #define debug_set_property(... )
1378     #elif ( DEBUG_GNU_VA_ARGS )
1379         #define debug_set_property( ARGS... )
1380     #else
1381         #define debug_set_property                  while( 0 )
1382     #endif
1383 #endif
1384
1385 #if 0
1386 #pragma mark == Routines - Debugging Output ==
1387 #endif
1388
1389 //---------------------------------------------------------------------------------------------------------------------------
1390 /*!     @function       DebugPrintF
1391
1392     @abstract   Prints a debug message with printf-style formatting.
1393
1394     @param              inLevel Error that generated this assert or noErr.
1395
1396     @param              inFormatString
1397                     C string containing assertion text.
1398
1399     @param              VAR_ARG
1400                     Variable number of arguments depending on the format string.
1401
1402     @result             Number of bytes printed or -1 on error.
1403  */
1404
1405 #if ( DEBUG )
1406 DEBUG_EXPORT size_t     DebugPrintF( DebugLevel inLevel, const char *inFormat, ... );
1407 #endif
1408
1409 //---------------------------------------------------------------------------------------------------------------------------
1410 /*!     @function       DebugPrintFVAList
1411
1412     @abstract   va_list version of DebugPrintF. See DebugPrintF for more info.
1413  */
1414
1415 #if ( DEBUG )
1416 DEBUG_EXPORT size_t     DebugPrintFVAList( DebugLevel inLevel, const char *inFormat, va_list inArgs );
1417 #endif
1418
1419 //---------------------------------------------------------------------------------------------------------------------------
1420 /*!     @function       DebugPrintAssert
1421
1422     @abstract   Prints a message describing the reason the (e.g. an assert failed), an optional error message,
1423                 an optional source filename, an optional source line number.
1424
1425     @param              inErrorCode                     Error that generated this assert or noErr.
1426     @param              inAssertString          C string containing assertion text.
1427     @param              inMessage                       C string containing a message about the assert.
1428     @param              inFileName                      C string containing path of file where the error occurred.
1429     @param              inLineNumber            Line number in source file where the error occurred.
1430     @param              inFunction                      C string containing name of function where assert occurred.
1431
1432     @discussion
1433
1434     Example output:
1435
1436     [ASSERT] assert: "dataPtr != NULL" allocate memory for object failed
1437     [ASSERT] where:  "MyFile.c", line 123, ("MyFunction")
1438
1439     OR
1440
1441     [ASSERT] error:  -6728 (kNoMemoryErr)
1442     [ASSERT] where:  "MyFile.c", line 123, ("MyFunction")
1443  */
1444
1445 #if ( DEBUG )
1446 DEBUG_EXPORT void
1447 DebugPrintAssert(
1448     int_least32_t inErrorCode,
1449     const char *    inAssertString,
1450     const char *    inMessage,
1451     const char *    inFilename,
1452     int_least32_t inLineNumber,
1453     const char *    inFunction );
1454 #endif
1455
1456 #if 0
1457 #pragma mark == Routines - Utilities ==
1458 #endif
1459
1460 //---------------------------------------------------------------------------------------------------------------------------
1461 /*!     @function       DebugSNPrintF
1462
1463     @abstract   Debugging versions of standard C snprintf with extra features.
1464
1465     @param              sbuffer         Buffer to receive result. Null terminated unless the buffer size is 0.
1466     @param              buflen          Size of the buffer including space for the null terminator.
1467     @param              fmt                     printf-style format string.
1468     @param              VAR_ARG         Variable number of arguments depending on the format string.
1469
1470     @result             Number of characters written (minus the null terminator).
1471
1472     @discussion
1473
1474     Extra features over the standard C snprintf:
1475     <pre>
1476         64-bit support for %d (%lld), %i (%lli), %u (%llu), %o (%llo), %x (%llx), and %b (%llb).
1477         %@   - Cocoa/CoreFoundation object. Param is the object. Strings are used directly. Others use CFCopyDescription.
1478         %a   - Network Address: %.4a=IPv4, %.6a=Ethernet, %.8a Fibre Channel, %.16a=IPv6. Arg=ptr to network address.
1479         %#a  - IPv4 or IPv6 mDNSAddr. Arg=ptr to mDNSAddr.
1480         %##a - IPv4 (if AF_INET defined) or IPv6 (if AF_INET6 defined) sockaddr. Arg=ptr to sockaddr.
1481         %b   - Binary representation of integer (e.g. 01101011). Modifiers and arg=the same as %d, %x, etc.
1482         %C   - Mac-style FourCharCode (e.g. 'APPL'). Arg=32-bit value to print as a Mac-style FourCharCode.
1483         %H   - Hex Dump (e.g. "\x6b\xa7" -> "6B A7"). 1st arg=ptr, 2nd arg=size, 3rd arg=max size.
1484         %#H  - Hex Dump & ASCII (e.g. "\x41\x62" -> "6B A7 'Ab'"). 1st arg=ptr, 2nd arg=size, 3rd arg=max size.
1485         %m   - Error Message (e.g. 0 -> "kNoErr"). Modifiers and error code arg=the same as %d, %x, etc.
1486         %#s  - Pascal-style length-prefixed string. Arg=ptr to string.
1487         %##s - DNS label-sequence name. Arg=ptr to name.
1488         %S   - UTF-16 string, 0x0000 terminated. Host order if no BOM. Precision is UTF-16 count. Precision includes BOM.
1489         %#S  - Big Endian UTF-16 string (unless BOM overrides). Otherwise, the same as %S.
1490         %##S - Little Endian UTF-16 string (unless BOM overrides). Otherwise, the same as %S.
1491         %U   - Universally Unique Identifier (UUID) (e.g. 6ba7b810-9dad-11d1-80b4-00c04fd430c8). Arg=ptr to 16-byte UUID.
1492     </pre>
1493  */
1494
1495 #if ( DEBUG )
1496 DEBUG_EXPORT size_t DebugSNPrintF(char *sbuffer, size_t buflen, const char *fmt, ...);
1497 #endif
1498
1499 //---------------------------------------------------------------------------------------------------------------------------
1500 /*!     @function       DebugSNPrintFVAList
1501
1502     @abstract   va_list version of DebugSNPrintF. See DebugSNPrintF for more info.
1503  */
1504
1505 #if ( DEBUG )
1506 DEBUG_EXPORT size_t DebugSNPrintFVAList(char *sbuffer, size_t buflen, const char *fmt, va_list arg);
1507 #endif
1508
1509 //---------------------------------------------------------------------------------------------------------------------------
1510 /*!     @function       DebugGetErrorString
1511
1512     @abstract   Gets an error string from an error code.
1513
1514     @param              inStatus                Error code to get the string for.
1515     @param              inBuffer                Optional buffer to copy the string to for non-static strings. May be null.
1516     @param              inBufferSize    Size of optional buffer. May be 0.
1517
1518     @result             C string containing error string for the error code. Guaranteed to be a valid, static string. If a
1519                 buffer is supplied, the return value will always be a pointer to the supplied buffer, which will
1520                 contain the best available description of the error code. If a buffer is not supplied, the return
1521                 value will be the best available description of the error code that can be represented as a static
1522                 string. This allows code that cannot use a temporary buffer to hold the result to still get a useful
1523                 error string in most cases, but also allows code that can use a temporary buffer to get the best
1524                 available description.
1525  */
1526
1527 #if ( DEBUG )
1528 DEBUG_EXPORT const char *   DebugGetErrorString( int_least32_t inErrorCode, char *inBuffer, size_t inBufferSize );
1529 #endif
1530
1531 //---------------------------------------------------------------------------------------------------------------------------
1532 /*!     @function       DebugHexDump
1533
1534     @abstract   Hex dumps data to a string or to the output device.
1535  */
1536
1537 #if ( DEBUG )
1538 DEBUG_EXPORT size_t
1539 DebugHexDump(
1540     DebugLevel inLevel,
1541     int inIndent,
1542     const char *    inLabel,
1543     size_t inLabelSize,
1544     int inLabelMinWidth,
1545     const char *    inType,
1546     size_t inTypeSize,
1547     const void *    inDataStart,
1548     const void *    inData,
1549     size_t inDataSize,
1550     DebugFlags inFlags,
1551     char *          outBuffer,
1552     size_t inBufferSize );
1553 #endif
1554
1555 #if ( DEBUG )
1556     #define dloghex( LEVEL, INDENT, LABEL, LABEL_SIZE, LABEL_MIN_SIZE, TYPE, TYPE_SIZE, DATA_START, DATA, DATA_SIZE, FLAGS, BUFFER, BUFFER_SIZE )   \
1557     DebugHexDump( ( LEVEL ), (INDENT), ( LABEL ), ( LABEL_SIZE ), ( LABEL_MIN_SIZE ), ( TYPE ), ( TYPE_SIZE ),                              \
1558                   ( DATA_START ), ( DATA ), ( DATA_SIZE ), ( FLAGS ), ( BUFFER ), ( BUFFER_SIZE ) )
1559 #else
1560     #define dloghex( LEVEL, INDENT, LABEL, LABEL_SIZE, LABEL_MIN_SIZE, TYPE, TYPE_SIZE, DATA_START, DATA, DATA_SIZE, FLAGS, BUFFER, BUFFER_SIZE )
1561 #endif
1562
1563 //---------------------------------------------------------------------------------------------------------------------------
1564 /*!     @function       DebugTaskLevel
1565
1566     @abstract   Returns the current task level.
1567
1568     @result             Current task level
1569
1570     @discussion
1571
1572     Bit masks to isolate portions of the result (note that some masks may also need bit shifts to right justify):
1573     <pre>
1574         kDebugInterruptLevelMask                                - Indicates the current interrupt level (> 0 means interrupt time).
1575         kDebugInVBLTaskMask                                             - Indicates if a VBL task is currently being executed.
1576         kDebugInDeferredTaskMask                                - Indicates if a Deferred Task is currently being executed.
1577         kDebugInSecondaryInterruptHandlerMask   - Indicates if a Secondary Interrupt Handler is currently being executed.
1578         kDebugPageFaultFatalMask                                - Indicates if it is unsafe to cause a page fault (worse than interrupt time).
1579         kDebugMPTaskLevelMask                                   - Indicates if being called from an MP task.
1580         kDebugInterruptDepthMask                                - 0 means task level, 1 means in interrupt, > 1 means in nested interrupt.
1581     </pre>
1582
1583     Helpers:
1584     <pre>
1585         DebugExtractTaskLevelInterruptDepth()   - Macro to extract interrupt depth from task level value.
1586     </pre>
1587  */
1588
1589 #if ( DEBUG )
1590 DEBUG_EXPORT uint32_t   DebugTaskLevel( void );
1591 #endif
1592
1593 //---------------------------------------------------------------------------------------------------------------------------
1594 /*!     @function       DebugServicesTest
1595
1596     @abstract   Unit test.
1597  */
1598
1599 #if ( DEBUG )
1600 DEBUG_EXPORT OSStatus   DebugServicesTest( void );
1601 #endif
1602
1603 #ifdef  __cplusplus
1604 }
1605 #endif
1606
1607 #endif  // __DEBUG_SERVICES__