1 /* -*- Mode: C; tab-width: 4 -*- 2 * 3 * Copyright (c) 1997-2004, 2020 Apple 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 0 32 #pragma mark == Settings == 33 #endif 34 35 //=========================================================================================================================== 36 // Settings 37 //=========================================================================================================================== 38 39 // General 40 41 #if ( !defined( DEBUG ) ) 42 #define DEBUG 0 43 #endif 44 45 #if ( defined( NDEBUG ) && DEBUG ) 46 #error NDEBUG defined and DEBUG is also enabled...they need to be in-sync 47 #endif 48 49 // AssertMacros.h/Debugging.h overrides. 50 51 #if ( !defined( DEBUG_OVERRIDE_APPLE_MACROS ) ) 52 #define DEBUG_OVERRIDE_APPLE_MACROS 1 53 #endif 54 55 // Routine name. Uses ISO __func__ where possible. Otherwise, uses the best thing that is available (if anything). 56 57 #if ( defined( __MWERKS__ ) || ( __GNUC__ > 2 ) || ( ( __GNUC__ == 2 ) && ( __GNUC_MINOR__ >= 9 ) ) ) 58 #define __ROUTINE__ __func__ 59 #elif ( defined( __GNUC__ ) ) 60 #define __ROUTINE__ __PRETTY_FUNCTION__ 61 #elif ( defined( _MSC_VER ) && !defined( _WIN32_WCE ) ) 62 #define __ROUTINE__ __FUNCTION__ 63 #else 64 #define __ROUTINE__ "" 65 #endif 66 67 // Variable argument macro support. Use ANSI C99 __VA_ARGS__ where possible. Otherwise, use the next best thing. 68 69 #if ( defined( __GNUC__ ) ) 70 #if ( ( __GNUC__ > 3 ) || ( ( __GNUC__ == 3 ) && ( __GNUC_MINOR__ >= 3) ) ) 71 #define DEBUG_C99_VA_ARGS 1 72 #define DEBUG_GNU_VA_ARGS 0 73 #else 74 #define DEBUG_C99_VA_ARGS 0 75 #define DEBUG_GNU_VA_ARGS 1 76 #endif 77 #elif ( defined( __MWERKS__ ) ) 78 #define DEBUG_C99_VA_ARGS 1 79 #define DEBUG_GNU_VA_ARGS 0 80 #else 81 #define DEBUG_C99_VA_ARGS 0 82 #define DEBUG_GNU_VA_ARGS 0 83 #endif 84 85 #if 0 86 #pragma mark == Output == 87 #endif 88 89 //--------------------------------------------------------------------------------------------------------------------------- 90 /*! @defined DEBUG_FPRINTF_ENABLED 91 92 @abstract Enables ANSI C fprintf output. 93 */ 94 95 #if ( !defined( DEBUG_FPRINTF_ENABLED ) ) 96 #if ( !TARGET_API_MAC_OSX_KERNEL && !TARGET_OS_WINDOWS_CE ) 97 #define DEBUG_FPRINTF_ENABLED 1 98 #else 99 #define DEBUG_FPRINTF_ENABLED 0 100 #endif 101 #else 102 #if ( TARGET_API_MAC_OSX_KERNEL || TARGET_OS_WINDOWS_CE ) 103 #error fprintf enabled, but not supported on Mac OS X kernel or Windows CE 104 #endif 105 #endif 106 107 //--------------------------------------------------------------------------------------------------------------------------- 108 /*! @defined DEBUG_MAC_OS_X_IOLOG_ENABLED 109 110 @abstract Enables IOLog (Mac OS X Kernel) output. 111 */ 112 113 #if ( !defined( DEBUG_MAC_OS_X_IOLOG_ENABLED ) ) 114 #define DEBUG_MAC_OS_X_IOLOG_ENABLED TARGET_API_MAC_OSX_KERNEL 115 #endif 116 117 //--------------------------------------------------------------------------------------------------------------------------- 118 /*! @defined DEBUG_KPRINTF_ENABLED 119 120 @abstract Enables kprintf (Mac OS X Kernel) output. 121 */ 122 123 #if ( !defined( DEBUG_KPRINTF_ENABLED ) ) 124 #define DEBUG_KPRINTF_ENABLED TARGET_API_MAC_OSX_KERNEL 125 #endif 126 127 //--------------------------------------------------------------------------------------------------------------------------- 128 /*! @defined DEBUG_IDEBUG_ENABLED 129 130 @abstract Enables iDebug (Mac OS X user and Kernel) output. 131 132 @discussion 133 134 For Mac OS X kernel development, iDebug is enabled by default because we can dynamically check for the presence 135 of iDebug via some exported IOKit symbols. Mac OS X app usage doesn't allow dynamic detection because it relies 136 on statically linking to the iDebugServices.cp file so for Mac OS X app usage, you have to manually enable iDebug. 137 */ 138 139 #if ( !defined( DEBUG_IDEBUG_ENABLED ) ) 140 #define DEBUG_IDEBUG_ENABLED TARGET_API_MAC_OSX_KERNEL 141 #endif 142 143 //--------------------------------------------------------------------------------------------------------------------------- 144 /*! @defined DEBUG_CORE_SERVICE_ASSERTS_ENABLED 145 146 @abstract Controls whether Core Services assert handling is enabled. Enabling requires CoreServices framework. 147 */ 148 149 #if ( !defined( DEBUG_CORE_SERVICE_ASSERTS_ENABLED ) ) 150 #if ( defined( __DEBUGGING__ ) ) 151 #define DEBUG_CORE_SERVICE_ASSERTS_ENABLED 1 152 #else 153 #define DEBUG_CORE_SERVICE_ASSERTS_ENABLED 0 154 #endif 155 #endif 156 157 //--------------------------------------------------------------------------------------------------------------------------- 158 /*! @typedef DebugOutputType 159 160 @abstract Type of debug output (i.e. where the output goes). 161 */ 162 163 typedef uint32_t DebugOutputType; 164 165 #define kDebugOutputTypeNone 0x6E6F6E65U // 'none' - no params 166 #define kDebugOutputTypeCustom 0x63757374U // 'cust' - 1st param = function ptr, 2nd param = context 167 #define kDebugOutputTypeFPrintF 0x66707269U // 'fpri' - 1st param = DebugOutputTypeFlags [, 2nd param = filename] 168 #define kDebugOutputTypeiDebug 0x69646267U // 'idbg' - no params 169 #define kDebugOutputTypeKPrintF 0x6B707266U // 'kprf' - no params 170 #define kDebugOutputTypeMacOSXIOLog 0x696C6F67U // 'ilog' - no params 171 #define kDebugOutputTypeMacOSXLog 0x786C6F67U // 'xlog' - no params 172 #define kDebugOutputTypeWindowsDebugger 0x77696E64U // 'wind' - no params 173 #define kDebugOutputTypeWindowsEventLog 0x7765766CU // 'wevl' - 1st param = C-string name, 2nd param = HMODULE or NULL. 174 175 // Console meta output kind - Any kind of Console output (in horizontal order of preference): 176 // 177 // Mac OS X = ANSI printf (viewable in Console.app) 178 // Mac OS X Kernel = IOLog (/var/log/system.log) or kprintf (serial). 179 // Windows = ANSI printf (Console window) or OutputDebugString (debugger). 180 // Other = ANSI printf (viewer varies). 181 182 #define kDebugOutputTypeMetaConsole 0x434F4E53U // 'CONS' - no params 183 184 //--------------------------------------------------------------------------------------------------------------------------- 185 /*! @typedef DebugOutputTypeFlags 186 187 @abstract Flags controlling how the output type is configured. 188 189 @constant kDebugOutputTypeFlagsTypeMask Bit mask for the output type (e.g. stdout, stderr, file, etc.). 190 @constant kDebugOutputTypeFlagsStdOut fprintf should go to stdout. 191 @constant kDebugOutputTypeFlagsStdErr fprintf should go to stderr. 192 @constant kDebugOutputTypeFlagsFile fprintf should go to a specific file (filename passed as va_arg). 193 */ 194 195 typedef unsigned int DebugOutputTypeFlags; 196 197 #define kDebugOutputTypeFlagsTypeMask 0xF 198 #define kDebugOutputTypeFlagsStdOut 1 199 #define kDebugOutputTypeFlagsStdErr 2 200 #define kDebugOutputTypeFlagsFile 10 201 202 //--------------------------------------------------------------------------------------------------------------------------- 203 /*! @typedef DebugOutputFunctionPtr 204 205 @abstract Function ptr for a custom callback to print debug output. 206 */ 207 208 typedef void ( *DebugOutputFunctionPtr )( char *inData, size_t inSize, void *inContext ); 209 210 //=========================================================================================================================== 211 // Constants 212 //=========================================================================================================================== 213 214 #if 0 215 #pragma mark == Flags == 216 #endif 217 218 //--------------------------------------------------------------------------------------------------------------------------- 219 /*! @typedef DebugFlags 220 221 @abstract Flags controlling how output is printed. 222 */ 223 224 typedef uint32_t DebugFlags; 225 226 #define kDebugFlagsNone 0 227 #define kDebugFlagsNoAddress ( 1 << 0 ) 228 #define kDebugFlagsNoOffset ( 1 << 1 ) 229 #define kDebugFlags32BitOffset ( 1 << 2 ) 230 #define kDebugFlagsNoASCII ( 1 << 3 ) 231 #define kDebugFlagsNoNewLine ( 1 << 4 ) 232 #define kDebugFlags8BitSeparator ( 1 << 5 ) 233 #define kDebugFlags16BitSeparator ( 1 << 6 ) 234 #define kDebugFlagsNo32BitSeparator ( 1 << 7 ) 235 #define kDebugFlagsNo16ByteHexPad ( 1 << 8 ) 236 #define kDebugFlagsNoByteCount ( 1 << 9 ) 237 238 //--------------------------------------------------------------------------------------------------------------------------- 239 /*! @enum DebugTaskLevelFlags 240 241 @abstract Flags indicating the task level. 242 */ 243 244 enum 245 { 246 kDebugInterruptLevelShift = 0, 247 kDebugInterruptLevelMask = 0x00000007, 248 kDebugInVBLTaskMask = 0x00000010, 249 kDebugInDeferredTaskMask = 0x00000020, 250 kDebugInSecondaryInterruptHandlerMask = 0x00000040, 251 kDebugPageFaultFatalMask = 0x00000100, // There should be a "kPageFaultFatalMask" in Debugging.h. 252 kDebugMPTaskLevelMask = 0x00000200, // There should be a "kMPTaskLevelMask" in Debugging.h. 253 kDebugInterruptDepthShift = 16, 254 kDebugInterruptDepthMask = 0x00FF0000 255 }; 256 257 #define DebugExtractTaskLevelInterruptLevel( LEVEL ) \ 258 ( ( ( LEVEL ) &kDebugInterruptLevelMask ) >> kDebugInterruptLevelShift ) 259 260 #define DebugExtractTaskLevelInterruptDepth( LEVEL ) \ 261 ( ( ( LEVEL ) &kDebugInterruptDepthMask ) >> kDebugInterruptDepthShift ) 262 263 #if 0 264 #pragma mark == Levels == 265 #endif 266 267 //=========================================================================================================================== 268 // Constants & Types - Levels 269 //=========================================================================================================================== 270 271 //--------------------------------------------------------------------------------------------------------------------------- 272 /*! @typedef DebugLevel 273 274 @abstract Level used to control debug logging. 275 */ 276 277 typedef int32_t DebugLevel; 278 279 // Levels 280 281 #define kDebugLevelMask 0x0000FFFF 282 #define kDebugLevelChatty 100 283 #define kDebugLevelVerbose 500 284 #define kDebugLevelTrace 800 285 #define kDebugLevelInfo 1000 286 #define kDebugLevelNotice 3000 287 #define kDebugLevelWarning 5000 288 #define kDebugLevelAssert 6000 289 #define kDebugLevelRequire 7000 290 #define kDebugLevelError 8000 291 #define kDebugLevelCritical 9000 292 #define kDebugLevelAlert 10000 293 #define kDebugLevelEmergency 11000 294 #define kDebugLevelTragic 12000 295 #define kDebugLevelMax 0x0000FFFF 296 297 // Level Flags 298 299 #define kDebugLevelFlagMask 0xFFFF0000 300 #define kDebugLevelFlagStackTrace 0x00010000 301 #define kDebugLevelFlagDebugBreak 0x00020000 302 303 //--------------------------------------------------------------------------------------------------------------------------- 304 /*! @typedef LogLevel 305 306 @abstract Level used to control which events are logged. 307 */ 308 309 typedef int32_t LogLevel; 310 311 #define kLogLevelUninitialized -1L 312 #define kLogLevelAll 0L 313 #define kLogLevelChatty 100L 314 #define kLogLevelVerbose 500L 315 #define kLogLevelTrace 800L 316 #define kLogLevelInfo 1000L 317 #define kLogLevelNotice 3000L 318 #define kLogLevelWarning 4000L 319 #define kLogLevelAssert 6000L 320 #define kLogLevelRequire 7000L 321 #define kLogLevelError 8000L 322 #define kLogLevelCritical 9000L 323 #define kLogLevelAlert 10000L 324 #define kLogLevelEmergency 11000L 325 #define kLogLevelTragic 12000L 326 #define kLogLevelOff 0x0000FFFEL 327 328 #if 0 329 #pragma mark == Properties == 330 #endif 331 332 //--------------------------------------------------------------------------------------------------------------------------- 333 /*! @typedef DebugPropertyTag 334 335 @abstract Tag for properties. 336 */ 337 338 typedef uint32_t DebugPropertyTag; 339 340 #define kDebugPropertyTagPrintLevelMin 0x6D696E70U // 'minp' Get: 1st param = DebugLevel * 341 // Set: 1st param = DebugLevel 342 343 #define kDebugPropertyTagPrintLevel kDebugPropertyTagPrintLevelMin 344 345 #define kDebugPropertyTagPrintLevelMax 0x706D786CU // 'maxp' Get: 1st param = DebugLevel * 346 // Set: 1st param = DebugLevel 347 348 #define kDebugPropertyTagBreakLevel 0x62726B6CU // 'brkl' Get: 1st param = DebugLevel * 349 // Set: 1st param = DebugLevel 350 #if 0 351 #pragma mark == General macros == 352 #endif 353 354 //--------------------------------------------------------------------------------------------------------------------------- 355 /*! @defined DEBUG_UNUSED 356 357 @abstract Macro to mark a paramter as unused to avoid unused parameter warnings. 358 359 @discussion 360 361 There is no universally supported pragma/attribute for indicating a variable is unused. DEBUG_UNUSED lets us 362 indicate a variable is unused in a manner that is supported by most compilers. 363 */ 364 365 #define DEBUG_UNUSED( X ) (void)( X ) 366 367 //--------------------------------------------------------------------------------------------------------------------------- 368 /*! @defined DEBUG_USE_ONLY 369 370 @abstract Macro to mark a variable as used only when debugging is enabled. 371 372 @discussion 373 374 Variables are sometimes needed only for debugging. When debugging is turned off, these debug-only variables generate 375 compiler warnings about unused variables. To eliminate these warnings, use these macros to indicate variables that 376 are only used for debugging. 377 */ 378 379 #if ( DEBUG ) 380 #define DEBUG_USE_ONLY( X ) 381 #else 382 #define DEBUG_USE_ONLY( X ) (void)( X ) 383 #endif 384 385 //--------------------------------------------------------------------------------------------------------------------------- 386 /*! @defined DEBUG_LOCAL 387 388 @abstract Macros to make variables and functions static when debugging is off, but extern when debugging is on. 389 390 @discussion 391 392 Rather than using "static" directly, using this macros allows you to access these variables external while 393 debugging without being penalized for production builds. 394 */ 395 396 #if ( DEBUG ) 397 #define DEBUG_LOCAL 398 #else 399 #define DEBUG_LOCAL static 400 #endif 401 402 //--------------------------------------------------------------------------------------------------------------------------- 403 /*! @defined DEBUG_STATIC 404 405 @abstract Macros to make variables and functions static when debugging is off, but extern when debugging is on. 406 407 @discussion 408 409 Rather than using "static" directly, using this macros allows you to access these variables external while 410 debugging without being penalized for production builds. 411 */ 412 413 #if ( DEBUG ) 414 #define DEBUG_STATIC 415 #else 416 #define DEBUG_STATIC static 417 #endif 418 419 //--------------------------------------------------------------------------------------------------------------------------- 420 /*! @defined DEBUG_EXPORT 421 422 @abstract Macros to export variables. 423 424 @discussion 425 426 "__private_extern__" is a hack for IOKit to allow symbols to be exported from compilation units, but 427 // not exported outside a driver (IOKit uses a lame global namespace for symbols). This still does not 428 // solve the problem of multiple drivers in the same dependency chain since they share symbols. 429 */ 430 431 #if ( TARGET_API_MAC_OSX_KERNEL ) 432 #define DEBUG_EXPORT __private_extern__ 433 #else 434 #define DEBUG_EXPORT extern 435 #endif 436 437 //--------------------------------------------------------------------------------------------------------------------------- 438 /*! @defined debug_add 439 440 @abstract Macro to add (or subtract if negative) a value when debugging is on. Does nothing if debugging is off. 441 */ 442 443 #if ( DEBUG ) 444 #define debug_add( A, B ) ( A ) += ( B ) 445 #else 446 #define debug_add( A, B ) 447 #endif 448 449 //--------------------------------------------------------------------------------------------------------------------------- 450 /*! @defined debug_perform 451 452 @abstract Macro to perform something in debug-only builds. 453 */ 454 455 #if ( DEBUG ) 456 #define debug_perform( X ) do { X; } while( 0 ) 457 #else 458 #define debug_perform( X ) 459 #endif 460 461 //--------------------------------------------------------------------------------------------------------------------------- 462 /*! @function translate_errno 463 464 @abstract Returns 0 if the test success. If the test fails, returns errno if non-zero and othewise the alternate error. 465 */ 466 467 #define translate_errno( TEST, ERRNO, ALTERNATE_ERROR ) ( ( TEST ) ? 0 : ( ERRNO ) ? ( ERRNO ) : ( ALTERNATE_ERROR ) ) 468 469 #if 0 470 #pragma mark == Compile Time macros == 471 #endif 472 473 //--------------------------------------------------------------------------------------------------------------------------- 474 /*! @defined check_compile_time 475 476 @abstract Performs a compile-time check of something such as the size of an int. 477 478 @discussion 479 480 This declares an array with a size that is determined by a compile-time expression. If the expression evaluates 481 to 0, the array has a size of -1, which is illegal and generates a compile-time error. 482 483 For example: 484 485 check_compile_time( sizeof( int ) == 4 ); 486 487 Note: This only works with compile-time expressions. 488 Note: This only works in places where extern declarations are allowed (e.g. global scope). 489 490 References: 491 492 <http://www.jaggersoft.com/pubs/CVu11_3.html> 493 <http://www.jaggersoft.com/pubs/CVu11_5.html> 494 495 Note: The following macros differ from the macros on the www.jaggersoft.com web site because those versions do not 496 work with GCC due to GCC allow a zero-length array. Using a -1 condition turned out to be more portable. 497 */ 498 499 #ifndef check_compile_time 500 #define check_compile_time( X ) extern int debug_compile_time_name[ ( X ) ? 1 : -1 ] 501 #endif 502 503 //--------------------------------------------------------------------------------------------------------------------------- 504 /*! @defined check_compile_time_code 505 506 @abstract Perform a compile-time check, suitable for placement in code, of something such as the size of an int. 507 508 @discussion 509 510 This creates a switch statement with an existing case for 0 and an additional case using the result of a 511 compile-time expression. A switch statement cannot have two case labels with the same constant so if the 512 compile-time expression evaluates to 0, it is illegal and generates a compile-time error. If the compile-time 513 expression does not evaluate to 0, the resulting value is used as the case label and it compiles without error. 514 515 For example: 516 517 check_compile_time_code( sizeof( int ) == 4 ); 518 519 Note: This only works with compile-time expressions. 520 Note: This does not work in a global scope so it must be inside a function. 521 522 References: 523 524 <http://www.jaggersoft.com/pubs/CVu11_3.html> 525 <http://www.jaggersoft.com/pubs/CVu11_5.html> 526 */ 527 528 #ifndef check_compile_time_code 529 #define check_compile_time_code( X ) switch( 0 ) { case 0: case X:; } 530 #endif 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 ( defined(DEBUG_EXPECT_VERIFIED) && 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 #if 0 1251 #pragma mark == Routines - General == 1252 #endif 1253 1254 #ifdef __cplusplus 1255 extern "C" { 1256 #endif 1257 1258 //--------------------------------------------------------------------------------------------------------------------------- 1259 /*! @function DebugInitialize 1260 1261 @abstract Initializes the debugging library for a specific kind of output. 1262 1263 @param inType 1264 @param varArg Variable number parameters, controlled by the "inType" parameter. 1265 */ 1266 1267 #if ( DEBUG ) 1268 DEBUG_EXPORT OSStatus DebugInitialize( DebugOutputType inType, ... ); 1269 #endif 1270 1271 #if ( DEBUG ) 1272 #if ( DEBUG_C99_VA_ARGS ) 1273 #define debug_initialize(... ) DebugInitialize( __VA_ARGS__ ) 1274 #elif ( DEBUG_GNU_VA_ARGS ) 1275 #define debug_initialize( ARGS... ) DebugInitialize( ## ARGS ) 1276 #else 1277 #define debug_initialize DebugInitialize 1278 #endif 1279 #else 1280 #if ( DEBUG_C99_VA_ARGS ) 1281 #define debug_initialize(... ) 1282 #elif ( DEBUG_GNU_VA_ARGS ) 1283 #define debug_initialize( ARGS... ) 1284 #else 1285 #define debug_initialize while( 0 ) 1286 #endif 1287 #endif 1288 1289 //--------------------------------------------------------------------------------------------------------------------------- 1290 /*! @function DebugFinalize 1291 1292 @abstract Releases any resources used by the debugging library 1293 */ 1294 1295 #if ( DEBUG ) 1296 DEBUG_EXPORT void DebugFinalize( void ); 1297 #endif 1298 1299 #if ( DEBUG ) 1300 #define debug_terminate() DebugFinalize() 1301 #else 1302 #define debug_terminate() 1303 #endif 1304 1305 //--------------------------------------------------------------------------------------------------------------------------- 1306 /*! @function DebugGetProperty 1307 1308 @abstract Gets the specified property from the debugging library. 1309 */ 1310 1311 #if ( DEBUG ) 1312 DEBUG_EXPORT OSStatus DebugGetProperty( DebugPropertyTag inTag, ... ); 1313 #endif 1314 1315 #if ( DEBUG ) 1316 #if ( DEBUG_C99_VA_ARGS ) 1317 #define debug_get_property(... ) DebugGetProperty( __VA_ARGS__ ) 1318 #elif ( DEBUG_GNU_VA_ARGS ) 1319 #define debug_get_property( ARGS... ) DebugGetProperty( ## ARGS ) 1320 #else 1321 #define debug_get_property DebugGetProperty 1322 #endif 1323 #else 1324 #if ( DEBUG_C99_VA_ARGS ) 1325 #define debug_get_property(... ) 1326 #elif ( DEBUG_GNU_VA_ARGS ) 1327 #define debug_get_property( ARGS... ) 1328 #else 1329 #define debug_get_property while( 0 ) 1330 #endif 1331 #endif 1332 1333 //--------------------------------------------------------------------------------------------------------------------------- 1334 /*! @function DebugSetProperty 1335 1336 @abstract Sets the specified property from the debugging library. 1337 */ 1338 1339 #if ( DEBUG ) 1340 DEBUG_EXPORT OSStatus DebugSetProperty( DebugPropertyTag inTag, ... ); 1341 #endif 1342 1343 #if ( DEBUG ) 1344 #if ( DEBUG_C99_VA_ARGS ) 1345 #define debug_set_property(... ) DebugSetProperty( __VA_ARGS__ ) 1346 #elif ( DEBUG_GNU_VA_ARGS ) 1347 #define debug_set_property( ARGS... ) DebugSetProperty( ## ARGS ) 1348 #else 1349 #define debug_set_property DebugSetProperty 1350 #endif 1351 #else 1352 #if ( DEBUG_C99_VA_ARGS ) 1353 #define debug_set_property(... ) 1354 #elif ( DEBUG_GNU_VA_ARGS ) 1355 #define debug_set_property( ARGS... ) 1356 #else 1357 #define debug_set_property while( 0 ) 1358 #endif 1359 #endif 1360 1361 #if 0 1362 #pragma mark == Routines - Debugging Output == 1363 #endif 1364 1365 //--------------------------------------------------------------------------------------------------------------------------- 1366 /*! @function DebugPrintF 1367 1368 @abstract Prints a debug message with printf-style formatting. 1369 1370 @param inLevel Error that generated this assert or noErr. 1371 1372 @param inFormatString 1373 C string containing assertion text. 1374 1375 @param VAR_ARG 1376 Variable number of arguments depending on the format string. 1377 1378 @result Number of bytes printed or -1 on error. 1379 */ 1380 1381 #if ( DEBUG ) 1382 DEBUG_EXPORT size_t DebugPrintF( DebugLevel inLevel, const char *inFormat, ... ); 1383 #endif 1384 1385 //--------------------------------------------------------------------------------------------------------------------------- 1386 /*! @function DebugPrintFVAList 1387 1388 @abstract va_list version of DebugPrintF. See DebugPrintF for more info. 1389 */ 1390 1391 #if ( DEBUG ) 1392 DEBUG_EXPORT size_t DebugPrintFVAList( DebugLevel inLevel, const char *inFormat, va_list inArgs ); 1393 #endif 1394 1395 //--------------------------------------------------------------------------------------------------------------------------- 1396 /*! @function DebugPrintAssert 1397 1398 @abstract Prints a message describing the reason the (e.g. an assert failed), an optional error message, 1399 an optional source filename, an optional source line number. 1400 1401 @param inErrorCode Error that generated this assert or noErr. 1402 @param inAssertString C string containing assertion text. 1403 @param inMessage C string containing a message about the assert. 1404 @param inFileName C string containing path of file where the error occurred. 1405 @param inLineNumber Line number in source file where the error occurred. 1406 @param inFunction C string containing name of function where assert occurred. 1407 1408 @discussion 1409 1410 Example output: 1411 1412 [ASSERT] assert: "dataPtr != NULL" allocate memory for object failed 1413 [ASSERT] where: "MyFile.c", line 123, ("MyFunction") 1414 1415 OR 1416 1417 [ASSERT] error: -6728 (kNoMemoryErr) 1418 [ASSERT] where: "MyFile.c", line 123, ("MyFunction") 1419 */ 1420 1421 #if ( DEBUG ) 1422 DEBUG_EXPORT void 1423 DebugPrintAssert( 1424 int_least32_t inErrorCode, 1425 const char * inAssertString, 1426 const char * inMessage, 1427 const char * inFilename, 1428 int_least32_t inLineNumber, 1429 const char * inFunction ); 1430 #endif 1431 1432 #if 0 1433 #pragma mark == Routines - Utilities == 1434 #endif 1435 1436 //--------------------------------------------------------------------------------------------------------------------------- 1437 /*! @function DebugSNPrintF 1438 1439 @abstract Debugging versions of standard C snprintf with extra features. 1440 1441 @param sbuffer Buffer to receive result. Null terminated unless the buffer size is 0. 1442 @param buflen Size of the buffer including space for the null terminator. 1443 @param fmt printf-style format string. 1444 @param VAR_ARG Variable number of arguments depending on the format string. 1445 1446 @result Number of characters written (minus the null terminator). 1447 1448 @discussion 1449 1450 Extra features over the standard C snprintf: 1451 <pre> 1452 64-bit support for %d (%lld), %i (%lli), %u (%llu), %o (%llo), %x (%llx), and %b (%llb). 1453 %@ - Cocoa/CoreFoundation object. Param is the object. Strings are used directly. Others use CFCopyDescription. 1454 %a - Network Address: %.4a=IPv4, %.6a=Ethernet, %.8a Fibre Channel, %.16a=IPv6. Arg=ptr to network address. 1455 %#a - IPv4 or IPv6 mDNSAddr. Arg=ptr to mDNSAddr. 1456 %##a - IPv4 (if AF_INET defined) or IPv6 (if AF_INET6 defined) sockaddr. Arg=ptr to sockaddr. 1457 %b - Binary representation of integer (e.g. 01101011). Modifiers and arg=the same as %d, %x, etc. 1458 %C - Mac-style FourCharCode (e.g. 'APPL'). Arg=32-bit value to print as a Mac-style FourCharCode. 1459 %H - Hex Dump (e.g. "\x6b\xa7" -> "6B A7"). 1st arg=ptr, 2nd arg=size, 3rd arg=max size. 1460 %#H - Hex Dump & ASCII (e.g. "\x41\x62" -> "6B A7 'Ab'"). 1st arg=ptr, 2nd arg=size, 3rd arg=max size. 1461 %m - Error Message (e.g. 0 -> "kNoErr"). Modifiers and error code arg=the same as %d, %x, etc. 1462 %#s - Pascal-style length-prefixed string. Arg=ptr to string. 1463 %##s - DNS label-sequence name. Arg=ptr to name. 1464 %S - UTF-16 string, 0x0000 terminated. Host order if no BOM. Precision is UTF-16 count. Precision includes BOM. 1465 %#S - Big Endian UTF-16 string (unless BOM overrides). Otherwise, the same as %S. 1466 %##S - Little Endian UTF-16 string (unless BOM overrides). Otherwise, the same as %S. 1467 %U - Universally Unique Identifier (UUID) (e.g. 6ba7b810-9dad-11d1-80b4-00c04fd430c8). Arg=ptr to 16-byte UUID. 1468 </pre> 1469 */ 1470 1471 #if ( DEBUG ) 1472 DEBUG_EXPORT size_t DebugSNPrintF(char *sbuffer, size_t buflen, const char *fmt, ...); 1473 #endif 1474 1475 //--------------------------------------------------------------------------------------------------------------------------- 1476 /*! @function DebugSNPrintFVAList 1477 1478 @abstract va_list version of DebugSNPrintF. See DebugSNPrintF for more info. 1479 */ 1480 1481 #if ( DEBUG ) 1482 DEBUG_EXPORT size_t DebugSNPrintFVAList(char *sbuffer, size_t buflen, const char *fmt, va_list arg); 1483 #endif 1484 1485 //--------------------------------------------------------------------------------------------------------------------------- 1486 /*! @function DebugGetErrorString 1487 1488 @abstract Gets an error string from an error code. 1489 1490 @param inStatus Error code to get the string for. 1491 @param inBuffer Optional buffer to copy the string to for non-static strings. May be null. 1492 @param inBufferSize Size of optional buffer. May be 0. 1493 1494 @result C string containing error string for the error code. Guaranteed to be a valid, static string. If a 1495 buffer is supplied, the return value will always be a pointer to the supplied buffer, which will 1496 contain the best available description of the error code. If a buffer is not supplied, the return 1497 value will be the best available description of the error code that can be represented as a static 1498 string. This allows code that cannot use a temporary buffer to hold the result to still get a useful 1499 error string in most cases, but also allows code that can use a temporary buffer to get the best 1500 available description. 1501 */ 1502 1503 #if ( DEBUG ) 1504 DEBUG_EXPORT const char * DebugGetErrorString( long inErrorCode, char *inBuffer, size_t inBufferSize ); 1505 #endif 1506 1507 //--------------------------------------------------------------------------------------------------------------------------- 1508 /*! @function DebugHexDump 1509 1510 @abstract Hex dumps data to a string or to the output device. 1511 */ 1512 1513 #if ( DEBUG ) 1514 DEBUG_EXPORT size_t 1515 DebugHexDump( 1516 DebugLevel inLevel, 1517 int inIndent, 1518 const char * inLabel, 1519 size_t inLabelSize, 1520 int inLabelMinWidth, 1521 const char * inType, 1522 size_t inTypeSize, 1523 const void * inDataStart, 1524 const void * inData, 1525 size_t inDataSize, 1526 DebugFlags inFlags, 1527 char * outBuffer, 1528 size_t inBufferSize ); 1529 #endif 1530 1531 #if ( DEBUG ) 1532 #define dloghex( LEVEL, INDENT, LABEL, LABEL_SIZE, LABEL_MIN_SIZE, TYPE, TYPE_SIZE, DATA_START, DATA, DATA_SIZE, FLAGS, BUFFER, BUFFER_SIZE ) \ 1533 DebugHexDump( ( LEVEL ), (INDENT), ( LABEL ), ( LABEL_SIZE ), ( LABEL_MIN_SIZE ), ( TYPE ), ( TYPE_SIZE ), \ 1534 ( DATA_START ), ( DATA ), ( DATA_SIZE ), ( FLAGS ), ( BUFFER ), ( BUFFER_SIZE ) ) 1535 #else 1536 #define dloghex( LEVEL, INDENT, LABEL, LABEL_SIZE, LABEL_MIN_SIZE, TYPE, TYPE_SIZE, DATA_START, DATA, DATA_SIZE, FLAGS, BUFFER, BUFFER_SIZE ) 1537 #endif 1538 1539 //--------------------------------------------------------------------------------------------------------------------------- 1540 /*! @function DebugTaskLevel 1541 1542 @abstract Returns the current task level. 1543 1544 @result Current task level 1545 1546 @discussion 1547 1548 Bit masks to isolate portions of the result (note that some masks may also need bit shifts to right justify): 1549 <pre> 1550 kDebugInterruptLevelMask - Indicates the current interrupt level (> 0 means interrupt time). 1551 kDebugInVBLTaskMask - Indicates if a VBL task is currently being executed. 1552 kDebugInDeferredTaskMask - Indicates if a Deferred Task is currently being executed. 1553 kDebugInSecondaryInterruptHandlerMask - Indicates if a Secondary Interrupt Handler is currently being executed. 1554 kDebugPageFaultFatalMask - Indicates if it is unsafe to cause a page fault (worse than interrupt time). 1555 kDebugMPTaskLevelMask - Indicates if being called from an MP task. 1556 kDebugInterruptDepthMask - 0 means task level, 1 means in interrupt, > 1 means in nested interrupt. 1557 </pre> 1558 1559 Helpers: 1560 <pre> 1561 DebugExtractTaskLevelInterruptDepth() - Macro to extract interrupt depth from task level value. 1562 </pre> 1563 */ 1564 1565 #if ( DEBUG ) 1566 DEBUG_EXPORT uint32_t DebugTaskLevel( void ); 1567 #endif 1568 1569 //--------------------------------------------------------------------------------------------------------------------------- 1570 /*! @function DebugServicesTest 1571 1572 @abstract Unit test. 1573 */ 1574 1575 #if ( DEBUG ) 1576 DEBUG_EXPORT OSStatus DebugServicesTest( void ); 1577 #endif 1578 1579 #ifdef __cplusplus 1580 } 1581 #endif 1582 1583 #endif // __DEBUG_SERVICES__ 1584