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