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 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 #define check_compile_time( X ) extern int debug_compile_time_name[ ( X ) ? 1 : -1 ] 500 501 //--------------------------------------------------------------------------------------------------------------------------- 502 /*! @defined check_compile_time_code 503 504 @abstract Perform a compile-time check, suitable for placement in code, of something such as the size of an int. 505 506 @discussion 507 508 This creates a switch statement with an existing case for 0 and an additional case using the result of a 509 compile-time expression. A switch statement cannot have two case labels with the same constant so if the 510 compile-time expression evaluates to 0, it is illegal and generates a compile-time error. If the compile-time 511 expression does not evaluate to 0, the resulting value is used as the case label and it compiles without error. 512 513 For example: 514 515 check_compile_time_code( sizeof( int ) == 4 ); 516 517 Note: This only works with compile-time expressions. 518 Note: This does not work in a global scope so it must be inside a function. 519 520 References: 521 522 <http://www.jaggersoft.com/pubs/CVu11_3.html> 523 <http://www.jaggersoft.com/pubs/CVu11_5.html> 524 */ 525 526 #define check_compile_time_code( X ) switch( 0 ) { case 0: case X:; } 527 528 #if 0 529 #pragma mark == check macros == 530 #endif 531 532 //--------------------------------------------------------------------------------------------------------------------------- 533 /*! @defined check 534 535 @abstract Check that an expression is true (non-zero). 536 537 @discussion 538 539 If expression evalulates to false, this prints debugging information (actual expression string, file, line number, 540 function name, etc.) using the default debugging output method. 541 542 Code inside check() statements is not compiled into production builds. 543 */ 544 545 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 546 #undef check 547 #endif 548 #if ( !defined( check ) ) 549 #if ( DEBUG ) 550 #define check( X ) \ 551 do \ 552 { \ 553 if( !( X ) ) \ 554 { \ 555 debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \ 556 } \ 557 } while( 0 ) 558 #else 559 #define check( X ) 560 #endif 561 #endif 562 563 //--------------------------------------------------------------------------------------------------------------------------- 564 /*! @defined check_string 565 566 @abstract Check that an expression is true (non-zero) with an explanation. 567 568 @discussion 569 570 If expression evalulates to false, this prints debugging information (actual expression string, file, line number, 571 function name, etc.) and a custom explanation string using the default debugging output method. 572 573 Code inside check_string() statements is not compiled into production builds. 574 */ 575 576 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 577 #undef check_string 578 #endif 579 #if ( !defined( check_string ) ) 580 #if ( DEBUG ) 581 #define check_string( X, STR ) \ 582 do \ 583 { \ 584 if( !( X ) ) \ 585 { \ 586 debug_print_assert( 0, # X, STR, __FILE__, __LINE__, __ROUTINE__ ); \ 587 } \ 588 \ 589 } while( 0 ) 590 #else 591 #define check_string( X, STR ) 592 #endif 593 #endif 594 595 //--------------------------------------------------------------------------------------------------------------------------- 596 /*! @defined check_noerr 597 598 @abstract Check that an error code is noErr (0). 599 600 @discussion 601 602 If the error code is non-0, this prints debugging information (actual expression string, file, line number, 603 function name, etc.) using the default debugging output method. 604 605 Code inside check_noerr() statements is not compiled into production builds. 606 */ 607 608 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 609 #undef check_noerr 610 #endif 611 #if ( !defined( check_noerr ) ) 612 #if ( DEBUG ) 613 #define check_noerr( ERR ) \ 614 do \ 615 { \ 616 int_least32_t localErr; \ 617 \ 618 localErr = (int_least32_t)( ERR ); \ 619 if( localErr != 0 ) \ 620 { \ 621 debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ ); \ 622 } \ 623 \ 624 } while( 0 ) 625 #else 626 #define check_noerr( ERR ) 627 #endif 628 #endif 629 630 //--------------------------------------------------------------------------------------------------------------------------- 631 /*! @defined check_noerr_string 632 633 @abstract Check that an error code is noErr (0) with an explanation. 634 635 @discussion 636 637 If the error code is non-0, this prints debugging information (actual expression string, file, line number, 638 function name, etc.) and a custom explanation string using the default debugging output method. 639 640 Code inside check_noerr_string() statements is not compiled into production builds. 641 */ 642 643 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 644 #undef check_noerr_string 645 #endif 646 #if ( !defined( check_noerr_string ) ) 647 #if ( DEBUG ) 648 #define check_noerr_string( ERR, STR ) \ 649 do \ 650 { \ 651 int_least32_t localErr; \ 652 \ 653 localErr = (int_least32_t)( ERR ); \ 654 if( localErr != 0 ) \ 655 { \ 656 debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \ 657 } \ 658 \ 659 } while( 0 ) 660 #else 661 #define check_noerr_string( ERR, STR ) 662 #endif 663 #endif 664 665 //--------------------------------------------------------------------------------------------------------------------------- 666 /*! @defined check_translated_errno 667 668 @abstract Check a condition and prints errno (if non-zero) to the log. 669 670 @discussion 671 672 Code inside check_translated_errno() statements is not compiled into production builds. 673 */ 674 675 #if ( !defined( check_translated_errno ) ) 676 #if ( DEBUG ) 677 #define check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR ) \ 678 do \ 679 { \ 680 if( !( TEST ) ) \ 681 { \ 682 int_least32_t localErr; \ 683 \ 684 localErr = (int_least32_t)( ERRNO ); \ 685 localErr = ( localErr != 0 ) ? localErr : (int_least32_t)( ALTERNATE_ERROR ); \ 686 debug_print_assert( localErr, # TEST, NULL, __FILE__, __LINE__, __ROUTINE__ ); \ 687 } \ 688 \ 689 } while( 0 ) 690 #else 691 #define check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR ) 692 #endif 693 #endif 694 695 //--------------------------------------------------------------------------------------------------------------------------- 696 /*! @defined check_ptr_overlap 697 698 @abstract Checks that two ptrs do not overlap. 699 */ 700 701 #define check_ptr_overlap( P1, P1_SIZE, P2, P2_SIZE ) \ 702 do \ 703 { \ 704 check( !( ( (uintptr_t)( P1 ) >= (uintptr_t)( P2 ) ) && \ 705 ( (uintptr_t)( P1 ) < ( ( (uintptr_t)( P2 ) ) + ( P2_SIZE ) ) ) ) ); \ 706 check( !( ( (uintptr_t)( P2 ) >= (uintptr_t)( P1 ) ) && \ 707 ( (uintptr_t)( P2 ) < ( ( (uintptr_t)( P1 ) ) + ( P1_SIZE ) ) ) ) ); \ 708 \ 709 } while( 0 ) 710 711 #if 0 712 #pragma mark == require macros == 713 #endif 714 715 //--------------------------------------------------------------------------------------------------------------------------- 716 /*! @defined require 717 718 @abstract Requires that an expression evaluate to true. 719 720 @discussion 721 722 If expression evalulates to false, this prints debugging information (actual expression string, file, line number, 723 function name, etc.) using the default debugging output method then jumps to a label. 724 */ 725 726 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 727 #undef require 728 #endif 729 #if ( !defined( require ) ) 730 #define require( X, LABEL ) \ 731 do \ 732 { \ 733 if( !( X ) ) \ 734 { \ 735 debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \ 736 goto LABEL; \ 737 } \ 738 \ 739 } while( 0 ) 740 #endif 741 742 //--------------------------------------------------------------------------------------------------------------------------- 743 /*! @defined require_string 744 745 @abstract Requires that an expression evaluate to true with an explanation. 746 747 @discussion 748 749 If expression evalulates to false, this prints debugging information (actual expression string, file, line number, 750 function name, etc.) and a custom explanation string using the default debugging output method then jumps to a label. 751 */ 752 753 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 754 #undef require_string 755 #endif 756 #if ( !defined( require_string ) ) 757 #define require_string( X, LABEL, STR ) \ 758 do \ 759 { \ 760 if( !( X ) ) \ 761 { \ 762 debug_print_assert( 0, # X, STR, __FILE__, __LINE__, __ROUTINE__ ); \ 763 goto LABEL; \ 764 } \ 765 \ 766 } while( 0 ) 767 #endif 768 769 //--------------------------------------------------------------------------------------------------------------------------- 770 /*! @defined require_quiet 771 772 @abstract Requires that an expression evaluate to true. 773 774 @discussion 775 776 If expression evalulates to false, this jumps to a label. No debugging information is printed. 777 */ 778 779 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 780 #undef require_quiet 781 #endif 782 #if ( !defined( require_quiet ) ) 783 #define require_quiet( X, LABEL ) \ 784 do \ 785 { \ 786 if( !( X ) ) \ 787 { \ 788 goto LABEL; \ 789 } \ 790 \ 791 } while( 0 ) 792 #endif 793 794 //--------------------------------------------------------------------------------------------------------------------------- 795 /*! @defined require_noerr 796 797 @abstract Require that an error code is noErr (0). 798 799 @discussion 800 801 If the error code is non-0, this prints debugging information (actual expression string, file, line number, 802 function name, etc.) using the default debugging output method then jumps to a label. 803 */ 804 805 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 806 #undef require_noerr 807 #endif 808 #if ( !defined( require_noerr ) ) 809 #define require_noerr( ERR, LABEL ) \ 810 do \ 811 { \ 812 int_least32_t localErr; \ 813 \ 814 localErr = (int_least32_t)( ERR ); \ 815 if( localErr != 0 ) \ 816 { \ 817 debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ ); \ 818 goto LABEL; \ 819 } \ 820 \ 821 } while( 0 ) 822 #endif 823 824 //--------------------------------------------------------------------------------------------------------------------------- 825 /*! @defined require_noerr_string 826 827 @abstract Require that an error code is noErr (0). 828 829 @discussion 830 831 If the error code is non-0, this prints debugging information (actual expression string, file, line number, 832 function name, etc.), and a custom explanation string using the default debugging output method using the 833 default debugging output method then jumps to a label. 834 */ 835 836 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 837 #undef require_noerr_string 838 #endif 839 #if ( !defined( require_noerr_string ) ) 840 #define require_noerr_string( ERR, LABEL, STR ) \ 841 do \ 842 { \ 843 int_least32_t localErr; \ 844 \ 845 localErr = (int_least32_t)( ERR ); \ 846 if( localErr != 0 ) \ 847 { \ 848 debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \ 849 goto LABEL; \ 850 } \ 851 \ 852 } while( 0 ) 853 #endif 854 855 //--------------------------------------------------------------------------------------------------------------------------- 856 /*! @defined require_noerr_action_string 857 858 @abstract Require that an error code is noErr (0). 859 860 @discussion 861 862 If the error code is non-0, this prints debugging information (actual expression string, file, line number, 863 function name, etc.), and a custom explanation string using the default debugging output method using the 864 default debugging output method then executes an action and jumps to a label. 865 */ 866 867 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 868 #undef require_noerr_action_string 869 #endif 870 #if ( !defined( require_noerr_action_string ) ) 871 #define require_noerr_action_string( ERR, LABEL, ACTION, STR ) \ 872 do \ 873 { \ 874 int_least32_t localErr; \ 875 \ 876 localErr = (int_least32_t)( ERR ); \ 877 if( localErr != 0 ) \ 878 { \ 879 debug_print_assert( localErr, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \ 880 { ACTION; } \ 881 goto LABEL; \ 882 } \ 883 \ 884 } while( 0 ) 885 #endif 886 887 //--------------------------------------------------------------------------------------------------------------------------- 888 /*! @defined require_noerr_quiet 889 890 @abstract Require that an error code is noErr (0). 891 892 @discussion 893 894 If the error code is non-0, this jumps to a label. No debugging information is printed. 895 */ 896 897 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 898 #undef require_noerr_quiet 899 #endif 900 #if ( !defined( require_noerr_quiet ) ) 901 #define require_noerr_quiet( ERR, LABEL ) \ 902 do \ 903 { \ 904 if( ( ERR ) != 0 ) \ 905 { \ 906 goto LABEL; \ 907 } \ 908 \ 909 } while( 0 ) 910 #endif 911 912 //--------------------------------------------------------------------------------------------------------------------------- 913 /*! @defined require_noerr_action 914 915 @abstract Require that an error code is noErr (0) with an action to execute otherwise. 916 917 @discussion 918 919 If the error code is non-0, this prints debugging information (actual expression string, file, line number, 920 function name, etc.) using the default debugging output method then executes an action and jumps to a label. 921 */ 922 923 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 924 #undef require_noerr_action 925 #endif 926 #if ( !defined( require_noerr_action ) ) 927 #define require_noerr_action( ERR, LABEL, ACTION ) \ 928 do \ 929 { \ 930 int_least32_t localErr; \ 931 \ 932 localErr = (int_least32_t)( ERR ); \ 933 if( localErr != 0 ) \ 934 { \ 935 debug_print_assert( localErr, NULL, NULL, __FILE__, __LINE__, __ROUTINE__ ); \ 936 { ACTION; } \ 937 goto LABEL; \ 938 } \ 939 \ 940 } while( 0 ) 941 #endif 942 943 //--------------------------------------------------------------------------------------------------------------------------- 944 /*! @defined require_noerr_action_quiet 945 946 @abstract Require that an error code is noErr (0) with an action to execute otherwise. 947 948 @discussion 949 950 If the error code is non-0, this executes an action and jumps to a label. No debugging information is printed. 951 */ 952 953 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 954 #undef require_noerr_action_quiet 955 #endif 956 #if ( !defined( require_noerr_action_quiet ) ) 957 #define require_noerr_action_quiet( ERR, LABEL, ACTION ) \ 958 do \ 959 { \ 960 if( ( ERR ) != 0 ) \ 961 { \ 962 { ACTION; } \ 963 goto LABEL; \ 964 } \ 965 \ 966 } while( 0 ) 967 #endif 968 969 //--------------------------------------------------------------------------------------------------------------------------- 970 /*! @defined require_action 971 972 @abstract Requires that an expression evaluate to true with an action to execute otherwise. 973 974 @discussion 975 976 If expression evalulates to false, this prints debugging information (actual expression string, file, line number, 977 function name, etc.) using the default debugging output method then executes an action and jumps to a label. 978 */ 979 980 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 981 #undef require_action 982 #endif 983 #if ( !defined( require_action ) ) 984 #define require_action( X, LABEL, ACTION ) \ 985 do \ 986 { \ 987 if( !( X ) ) \ 988 { \ 989 debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \ 990 { ACTION; } \ 991 goto LABEL; \ 992 } \ 993 \ 994 } while( 0 ) 995 #endif 996 997 //--------------------------------------------------------------------------------------------------------------------------- 998 /*! @defined require_action_quiet 999 1000 @abstract Requires that an expression evaluate to true with an action to execute otherwise. 1001 1002 @discussion 1003 1004 If expression evalulates to false, this executes an action and jumps to a label. No debugging information is printed. 1005 */ 1006 1007 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 1008 #undef require_action_quiet 1009 #endif 1010 #if ( !defined( require_action_quiet ) ) 1011 #define require_action_quiet( X, LABEL, ACTION ) \ 1012 do \ 1013 { \ 1014 if( !( X ) ) \ 1015 { \ 1016 { ACTION; } \ 1017 goto LABEL; \ 1018 } \ 1019 \ 1020 } while( 0 ) 1021 #endif 1022 1023 //--------------------------------------------------------------------------------------------------------------------------- 1024 /*! @defined require_action_string 1025 1026 @abstract Requires that an expression evaluate to true with an explanation and action to execute otherwise. 1027 1028 @discussion 1029 1030 If expression evalulates to false, this prints debugging information (actual expression string, file, line number, 1031 function name, etc.) and a custom explanation string using the default debugging output method then executes an 1032 action and jumps to a label. 1033 */ 1034 1035 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 1036 #undef require_action_string 1037 #endif 1038 #if ( !defined( require_action_string ) ) 1039 #define require_action_string( X, LABEL, ACTION, STR ) \ 1040 do \ 1041 { \ 1042 if( !( X ) ) \ 1043 { \ 1044 debug_print_assert( 0, # X, STR, __FILE__, __LINE__, __ROUTINE__ ); \ 1045 { ACTION; } \ 1046 goto LABEL; \ 1047 } \ 1048 \ 1049 } while( 0 ) 1050 1051 #endif 1052 1053 //--------------------------------------------------------------------------------------------------------------------------- 1054 /*! @defined require_throw 1055 1056 @abstract Requires that an expression evaluates to true or an exception is thrown. 1057 1058 @discussion 1059 1060 If the expression evaluates to false, this prints debugging information (actual expression string, file, 1061 line number, function name, etc.) using the default debugging output method then throws an exception. 1062 */ 1063 1064 #if ( defined( __cplusplus ) ) 1065 #define require_throw( X ) \ 1066 do \ 1067 { \ 1068 if( !( X ) ) \ 1069 { \ 1070 debug_print_assert( 0, # X, NULL, __FILE__, __LINE__, __ROUTINE__ ); \ 1071 throw kUnknownErr; \ 1072 } \ 1073 \ 1074 } while( 0 ) 1075 #endif 1076 1077 #if 0 1078 #pragma mark == Design-By-Contract macros == 1079 #endif 1080 1081 //=========================================================================================================================== 1082 // Design-By-Contract macros 1083 //=========================================================================================================================== 1084 1085 #define ensure( X ) check( X ) 1086 #define ensure_string( X, STR ) check_string( X, STR ) 1087 #define ensure_noerr( ERR ) check_noerr( ERR ) 1088 #define ensure_noerr_string( ERR, STR ) check_noerr_string( ERR, STR ) 1089 #define ensure_translated_errno( TEST, ERRNO, ALTERNATE_ERROR ) check_translated_errno( TEST, ERRNO, ALTERNATE_ERROR ) 1090 1091 // Note: Design-By-Contract "require" macros are already defined elsewhere. 1092 1093 #if 0 1094 #pragma mark == Expect macros == 1095 #endif 1096 1097 //=========================================================================================================================== 1098 // Expect macros 1099 //=========================================================================================================================== 1100 1101 // Expect macros allow code to include runtime checking of things that should not happen in shipping code (e.g. internal 1102 // programmer errors, such as a NULL parameter where it is not allowed). Once the code has been verified to work correctly 1103 // without asserting, the DEBUG_EXPECT_VERIFIED conditional can be set to eliminate the error checking entirely. It can 1104 // also be useful to measure the cost of error checking code by profiling with it enable and with it disabled. 1105 1106 #if ( DEBUG_EXPECT_VERIFIED ) 1107 #define require_expect 1108 #define require_string_expect 1109 #define require_quiet_expect 1110 #define require_noerr_expect 1111 #define require_noerr_string_expect 1112 #define require_noerr_action_string_expect 1113 #define require_noerr_quiet_expect 1114 #define require_noerr_action_expect 1115 #define require_noerr_action_quiet_expect 1116 #define require_action_expect 1117 #define require_action_quiet_expect 1118 #define require_action_string_expect 1119 #else 1120 #define require_expect require 1121 #define require_string_expect require_string 1122 #define require_quiet_expect require_quiet 1123 #define require_noerr_expect require_noerr 1124 #define require_noerr_string_expect require_noerr_string 1125 #define require_noerr_action_string_expect require_noerr_action_string 1126 #define require_noerr_quiet_expect require_noerr_quiet 1127 #define require_noerr_action_expect require_noerr_action 1128 #define require_noerr_action_quiet_expect require_noerr_action_quiet 1129 #define require_action_expect require_action 1130 #define require_action_quiet_expect require_action_quiet 1131 #define require_action_string_expect require_action_string 1132 #endif 1133 1134 #if 0 1135 #pragma mark == Output macros == 1136 #endif 1137 1138 //--------------------------------------------------------------------------------------------------------------------------- 1139 /*! @defined debug_string 1140 1141 @abstract Prints a debugging C string. 1142 */ 1143 1144 #if ( DEBUG_OVERRIDE_APPLE_MACROS ) 1145 #undef debug_string 1146 #endif 1147 #if ( !defined( debug_string ) ) 1148 #if ( DEBUG ) 1149 #define debug_string( STR ) \ 1150 do \ 1151 { \ 1152 debug_print_assert( 0, NULL, STR, __FILE__, __LINE__, __ROUTINE__ ); \ 1153 \ 1154 } while( 0 ) 1155 #else 1156 #define debug_string( STR ) 1157 #endif 1158 #endif 1159 1160 //--------------------------------------------------------------------------------------------------------------------------- 1161 /*! @defined debug_print_assert 1162 1163 @abstract Prints an assertion. 1164 */ 1165 1166 #if ( DEBUG ) 1167 #define debug_print_assert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION ) \ 1168 DebugPrintAssert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION ) 1169 #else 1170 #define debug_print_assert( ERROR_CODE, ASSERT_STRING, MESSAGE, FILENAME, LINE_NUMBER, FUNCTION ) 1171 #endif 1172 1173 //--------------------------------------------------------------------------------------------------------------------------- 1174 /*! @defined dlog 1175 1176 @abstract Prints a debug-only message. 1177 */ 1178 1179 #if ( DEBUG ) 1180 #if ( DEBUG_C99_VA_ARGS ) 1181 #define dlog(... ) DebugPrintF( __VA_ARGS__ ) 1182 #elif ( DEBUG_GNU_VA_ARGS ) 1183 #define dlog( ARGS... ) DebugPrintF( ## ARGS ) 1184 #else 1185 #define dlog DebugPrintF 1186 #endif 1187 #else 1188 #if ( DEBUG_C99_VA_ARGS ) 1189 #define dlog(... ) 1190 #elif ( DEBUG_GNU_VA_ARGS ) 1191 #define dlog( ARGS... ) 1192 #else 1193 #define dlog while( 0 ) 1194 #endif 1195 #endif 1196 1197 //--------------------------------------------------------------------------------------------------------------------------- 1198 /*! @defined dlogv 1199 1200 @abstract Prints a debug-only message. 1201 */ 1202 1203 #if ( DEBUG ) 1204 #define dlogv( LEVEL, FORMAT, LIST ) DebugPrintFVAList( ( LEVEL ), ( FORMAT ), ( LIST ) ) 1205 #else 1206 #define dlogv( LEVEL, FORMAT, LIST ) 1207 #endif 1208 1209 //--------------------------------------------------------------------------------------------------------------------------- 1210 /*! @defined dlogmem 1211 1212 @abstract Prints a debug-only dump of memory. 1213 */ 1214 1215 #if ( DEBUG ) 1216 #define dlogmem( LEVEL, PTR, SIZE ) \ 1217 DebugHexDump( ( LEVEL ), 0, NULL, 0, 0, NULL, 0, ( PTR ), ( PTR ), ( SIZE ), kDebugFlagsNone, NULL, 0 ) 1218 #else 1219 #define dlogmem( LEVEL, PTR, SIZE ) 1220 #endif 1221 1222 //--------------------------------------------------------------------------------------------------------------------------- 1223 /*! @defined DebugNSLog 1224 1225 @abstract Debug-only macro for the Cocoa NSLog function. 1226 */ 1227 1228 #if ( DEBUG ) 1229 #if ( DEBUG_C99_VA_ARGS ) 1230 #define DebugNSLog(... ) NSLog( __VA_ARGS__ ) 1231 #elif ( DEBUG_GNU_VA_ARGS ) 1232 #define DebugNSLog( ARGS... ) NSLog( ## ARGS ) 1233 #else 1234 #define DebugNSLog NSLog 1235 #endif 1236 #else 1237 #if ( DEBUG_C99_VA_ARGS ) 1238 #define DebugNSLog(... ) 1239 #elif ( DEBUG_GNU_VA_ARGS ) 1240 #define DebugNSLog( ARGS... ) 1241 #else 1242 #define DebugNSLog while( 0 ) 1243 #endif 1244 #endif 1245 1246 #if 0 1247 #pragma mark == Routines - General == 1248 #endif 1249 1250 #ifdef __cplusplus 1251 extern "C" { 1252 #endif 1253 1254 //--------------------------------------------------------------------------------------------------------------------------- 1255 /*! @function DebugInitialize 1256 1257 @abstract Initializes the debugging library for a specific kind of output. 1258 1259 @param inType 1260 @param varArg Variable number parameters, controlled by the "inType" parameter. 1261 */ 1262 1263 #if ( DEBUG ) 1264 DEBUG_EXPORT OSStatus DebugInitialize( DebugOutputType inType, ... ); 1265 #endif 1266 1267 #if ( DEBUG ) 1268 #if ( DEBUG_C99_VA_ARGS ) 1269 #define debug_initialize(... ) DebugInitialize( __VA_ARGS__ ) 1270 #elif ( DEBUG_GNU_VA_ARGS ) 1271 #define debug_initialize( ARGS... ) DebugInitialize( ## ARGS ) 1272 #else 1273 #define debug_initialize DebugInitialize 1274 #endif 1275 #else 1276 #if ( DEBUG_C99_VA_ARGS ) 1277 #define debug_initialize(... ) 1278 #elif ( DEBUG_GNU_VA_ARGS ) 1279 #define debug_initialize( ARGS... ) 1280 #else 1281 #define debug_initialize while( 0 ) 1282 #endif 1283 #endif 1284 1285 //--------------------------------------------------------------------------------------------------------------------------- 1286 /*! @function DebugFinalize 1287 1288 @abstract Releases any resources used by the debugging library 1289 */ 1290 1291 #if ( DEBUG ) 1292 DEBUG_EXPORT void DebugFinalize( void ); 1293 #endif 1294 1295 #if ( DEBUG ) 1296 #define debug_terminate() DebugFinalize() 1297 #else 1298 #define debug_terminate() 1299 #endif 1300 1301 //--------------------------------------------------------------------------------------------------------------------------- 1302 /*! @function DebugGetProperty 1303 1304 @abstract Gets the specified property from the debugging library. 1305 */ 1306 1307 #if ( DEBUG ) 1308 DEBUG_EXPORT OSStatus DebugGetProperty( DebugPropertyTag inTag, ... ); 1309 #endif 1310 1311 #if ( DEBUG ) 1312 #if ( DEBUG_C99_VA_ARGS ) 1313 #define debug_get_property(... ) DebugGetProperty( __VA_ARGS__ ) 1314 #elif ( DEBUG_GNU_VA_ARGS ) 1315 #define debug_get_property( ARGS... ) DebugGetProperty( ## ARGS ) 1316 #else 1317 #define debug_get_property DebugGetProperty 1318 #endif 1319 #else 1320 #if ( DEBUG_C99_VA_ARGS ) 1321 #define debug_get_property(... ) 1322 #elif ( DEBUG_GNU_VA_ARGS ) 1323 #define debug_get_property( ARGS... ) 1324 #else 1325 #define debug_get_property while( 0 ) 1326 #endif 1327 #endif 1328 1329 //--------------------------------------------------------------------------------------------------------------------------- 1330 /*! @function DebugSetProperty 1331 1332 @abstract Sets the specified property from the debugging library. 1333 */ 1334 1335 #if ( DEBUG ) 1336 DEBUG_EXPORT OSStatus DebugSetProperty( DebugPropertyTag inTag, ... ); 1337 #endif 1338 1339 #if ( DEBUG ) 1340 #if ( DEBUG_C99_VA_ARGS ) 1341 #define debug_set_property(... ) DebugSetProperty( __VA_ARGS__ ) 1342 #elif ( DEBUG_GNU_VA_ARGS ) 1343 #define debug_set_property( ARGS... ) DebugSetProperty( ## ARGS ) 1344 #else 1345 #define debug_set_property DebugSetProperty 1346 #endif 1347 #else 1348 #if ( DEBUG_C99_VA_ARGS ) 1349 #define debug_set_property(... ) 1350 #elif ( DEBUG_GNU_VA_ARGS ) 1351 #define debug_set_property( ARGS... ) 1352 #else 1353 #define debug_set_property while( 0 ) 1354 #endif 1355 #endif 1356 1357 #if 0 1358 #pragma mark == Routines - Debugging Output == 1359 #endif 1360 1361 //--------------------------------------------------------------------------------------------------------------------------- 1362 /*! @function DebugPrintF 1363 1364 @abstract Prints a debug message with printf-style formatting. 1365 1366 @param inLevel Error that generated this assert or noErr. 1367 1368 @param inFormatString 1369 C string containing assertion text. 1370 1371 @param VAR_ARG 1372 Variable number of arguments depending on the format string. 1373 1374 @result Number of bytes printed or -1 on error. 1375 */ 1376 1377 #if ( DEBUG ) 1378 DEBUG_EXPORT size_t DebugPrintF( DebugLevel inLevel, const char *inFormat, ... ); 1379 #endif 1380 1381 //--------------------------------------------------------------------------------------------------------------------------- 1382 /*! @function DebugPrintFVAList 1383 1384 @abstract va_list version of DebugPrintF. See DebugPrintF for more info. 1385 */ 1386 1387 #if ( DEBUG ) 1388 DEBUG_EXPORT size_t DebugPrintFVAList( DebugLevel inLevel, const char *inFormat, va_list inArgs ); 1389 #endif 1390 1391 //--------------------------------------------------------------------------------------------------------------------------- 1392 /*! @function DebugPrintAssert 1393 1394 @abstract Prints a message describing the reason the (e.g. an assert failed), an optional error message, 1395 an optional source filename, an optional source line number. 1396 1397 @param inErrorCode Error that generated this assert or noErr. 1398 @param inAssertString C string containing assertion text. 1399 @param inMessage C string containing a message about the assert. 1400 @param inFileName C string containing path of file where the error occurred. 1401 @param inLineNumber Line number in source file where the error occurred. 1402 @param inFunction C string containing name of function where assert occurred. 1403 1404 @discussion 1405 1406 Example output: 1407 1408 [ASSERT] assert: "dataPtr != NULL" allocate memory for object failed 1409 [ASSERT] where: "MyFile.c", line 123, ("MyFunction") 1410 1411 OR 1412 1413 [ASSERT] error: -6728 (kNoMemoryErr) 1414 [ASSERT] where: "MyFile.c", line 123, ("MyFunction") 1415 */ 1416 1417 #if ( DEBUG ) 1418 DEBUG_EXPORT void 1419 DebugPrintAssert( 1420 int_least32_t inErrorCode, 1421 const char * inAssertString, 1422 const char * inMessage, 1423 const char * inFilename, 1424 int_least32_t inLineNumber, 1425 const char * inFunction ); 1426 #endif 1427 1428 #if 0 1429 #pragma mark == Routines - Utilities == 1430 #endif 1431 1432 //--------------------------------------------------------------------------------------------------------------------------- 1433 /*! @function DebugSNPrintF 1434 1435 @abstract Debugging versions of standard C snprintf with extra features. 1436 1437 @param sbuffer Buffer to receive result. Null terminated unless the buffer size is 0. 1438 @param buflen Size of the buffer including space for the null terminator. 1439 @param fmt printf-style format string. 1440 @param VAR_ARG Variable number of arguments depending on the format string. 1441 1442 @result Number of characters written (minus the null terminator). 1443 1444 @discussion 1445 1446 Extra features over the standard C snprintf: 1447 <pre> 1448 64-bit support for %d (%lld), %i (%lli), %u (%llu), %o (%llo), %x (%llx), and %b (%llb). 1449 %@ - Cocoa/CoreFoundation object. Param is the object. Strings are used directly. Others use CFCopyDescription. 1450 %a - Network Address: %.4a=IPv4, %.6a=Ethernet, %.8a Fibre Channel, %.16a=IPv6. Arg=ptr to network address. 1451 %#a - IPv4 or IPv6 mDNSAddr. Arg=ptr to mDNSAddr. 1452 %##a - IPv4 (if AF_INET defined) or IPv6 (if AF_INET6 defined) sockaddr. Arg=ptr to sockaddr. 1453 %b - Binary representation of integer (e.g. 01101011). Modifiers and arg=the same as %d, %x, etc. 1454 %C - Mac-style FourCharCode (e.g. 'APPL'). Arg=32-bit value to print as a Mac-style FourCharCode. 1455 %H - Hex Dump (e.g. "\x6b\xa7" -> "6B A7"). 1st arg=ptr, 2nd arg=size, 3rd arg=max size. 1456 %#H - Hex Dump & ASCII (e.g. "\x41\x62" -> "6B A7 'Ab'"). 1st arg=ptr, 2nd arg=size, 3rd arg=max size. 1457 %m - Error Message (e.g. 0 -> "kNoErr"). Modifiers and error code arg=the same as %d, %x, etc. 1458 %#s - Pascal-style length-prefixed string. Arg=ptr to string. 1459 %##s - DNS label-sequence name. Arg=ptr to name. 1460 %S - UTF-16 string, 0x0000 terminated. Host order if no BOM. Precision is UTF-16 count. Precision includes BOM. 1461 %#S - Big Endian UTF-16 string (unless BOM overrides). Otherwise, the same as %S. 1462 %##S - Little Endian UTF-16 string (unless BOM overrides). Otherwise, the same as %S. 1463 %U - Universally Unique Identifier (UUID) (e.g. 6ba7b810-9dad-11d1-80b4-00c04fd430c8). Arg=ptr to 16-byte UUID. 1464 </pre> 1465 */ 1466 1467 #if ( DEBUG ) 1468 DEBUG_EXPORT size_t DebugSNPrintF(char *sbuffer, size_t buflen, const char *fmt, ...); 1469 #endif 1470 1471 //--------------------------------------------------------------------------------------------------------------------------- 1472 /*! @function DebugSNPrintFVAList 1473 1474 @abstract va_list version of DebugSNPrintF. See DebugSNPrintF for more info. 1475 */ 1476 1477 #if ( DEBUG ) 1478 DEBUG_EXPORT size_t DebugSNPrintFVAList(char *sbuffer, size_t buflen, const char *fmt, va_list arg); 1479 #endif 1480 1481 //--------------------------------------------------------------------------------------------------------------------------- 1482 /*! @function DebugGetErrorString 1483 1484 @abstract Gets an error string from an error code. 1485 1486 @param inStatus Error code to get the string for. 1487 @param inBuffer Optional buffer to copy the string to for non-static strings. May be null. 1488 @param inBufferSize Size of optional buffer. May be 0. 1489 1490 @result C string containing error string for the error code. Guaranteed to be a valid, static string. If a 1491 buffer is supplied, the return value will always be a pointer to the supplied buffer, which will 1492 contain the best available description of the error code. If a buffer is not supplied, the return 1493 value will be the best available description of the error code that can be represented as a static 1494 string. This allows code that cannot use a temporary buffer to hold the result to still get a useful 1495 error string in most cases, but also allows code that can use a temporary buffer to get the best 1496 available description. 1497 */ 1498 1499 #if ( DEBUG ) 1500 DEBUG_EXPORT const char * DebugGetErrorString( int_least32_t inErrorCode, char *inBuffer, size_t inBufferSize ); 1501 #endif 1502 1503 //--------------------------------------------------------------------------------------------------------------------------- 1504 /*! @function DebugHexDump 1505 1506 @abstract Hex dumps data to a string or to the output device. 1507 */ 1508 1509 #if ( DEBUG ) 1510 DEBUG_EXPORT size_t 1511 DebugHexDump( 1512 DebugLevel inLevel, 1513 int inIndent, 1514 const char * inLabel, 1515 size_t inLabelSize, 1516 int inLabelMinWidth, 1517 const char * inType, 1518 size_t inTypeSize, 1519 const void * inDataStart, 1520 const void * inData, 1521 size_t inDataSize, 1522 DebugFlags inFlags, 1523 char * outBuffer, 1524 size_t inBufferSize ); 1525 #endif 1526 1527 #if ( DEBUG ) 1528 #define dloghex( LEVEL, INDENT, LABEL, LABEL_SIZE, LABEL_MIN_SIZE, TYPE, TYPE_SIZE, DATA_START, DATA, DATA_SIZE, FLAGS, BUFFER, BUFFER_SIZE ) \ 1529 DebugHexDump( ( LEVEL ), (INDENT), ( LABEL ), ( LABEL_SIZE ), ( LABEL_MIN_SIZE ), ( TYPE ), ( TYPE_SIZE ), \ 1530 ( DATA_START ), ( DATA ), ( DATA_SIZE ), ( FLAGS ), ( BUFFER ), ( BUFFER_SIZE ) ) 1531 #else 1532 #define dloghex( LEVEL, INDENT, LABEL, LABEL_SIZE, LABEL_MIN_SIZE, TYPE, TYPE_SIZE, DATA_START, DATA, DATA_SIZE, FLAGS, BUFFER, BUFFER_SIZE ) 1533 #endif 1534 1535 //--------------------------------------------------------------------------------------------------------------------------- 1536 /*! @function DebugTaskLevel 1537 1538 @abstract Returns the current task level. 1539 1540 @result Current task level 1541 1542 @discussion 1543 1544 Bit masks to isolate portions of the result (note that some masks may also need bit shifts to right justify): 1545 <pre> 1546 kDebugInterruptLevelMask - Indicates the current interrupt level (> 0 means interrupt time). 1547 kDebugInVBLTaskMask - Indicates if a VBL task is currently being executed. 1548 kDebugInDeferredTaskMask - Indicates if a Deferred Task is currently being executed. 1549 kDebugInSecondaryInterruptHandlerMask - Indicates if a Secondary Interrupt Handler is currently being executed. 1550 kDebugPageFaultFatalMask - Indicates if it is unsafe to cause a page fault (worse than interrupt time). 1551 kDebugMPTaskLevelMask - Indicates if being called from an MP task. 1552 kDebugInterruptDepthMask - 0 means task level, 1 means in interrupt, > 1 means in nested interrupt. 1553 </pre> 1554 1555 Helpers: 1556 <pre> 1557 DebugExtractTaskLevelInterruptDepth() - Macro to extract interrupt depth from task level value. 1558 </pre> 1559 */ 1560 1561 #if ( DEBUG ) 1562 DEBUG_EXPORT uint32_t DebugTaskLevel( void ); 1563 #endif 1564 1565 //--------------------------------------------------------------------------------------------------------------------------- 1566 /*! @function DebugServicesTest 1567 1568 @abstract Unit test. 1569 */ 1570 1571 #if ( DEBUG ) 1572 DEBUG_EXPORT OSStatus DebugServicesTest( void ); 1573 #endif 1574 1575 #ifdef __cplusplus 1576 } 1577 #endif 1578 1579 #endif // __DEBUG_SERVICES__ 1580