u_debug.h 10.9 KB
Newer Older
1 2
/**************************************************************************
 * 
Jose Fonseca's avatar
Jose Fonseca committed
3
 * Copyright 2008 VMware, Inc.
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
 * All Rights Reserved.
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sub license, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 * 
 * The above copyright notice and this permission notice (including the
 * next paragraph) shall be included in all copies or substantial portions
 * of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
Jose Fonseca's avatar
Jose Fonseca committed
21
 * IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
22 23 24 25 26 27 28 29 30 31 32 33 34
 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 * 
 **************************************************************************/

/**
 * @file
 * Cross-platform debugging helpers.
 * 
 * For now it just has assert and printf replacements, but it might be extended 
 * with stack trace reports and more advanced logging in the near future. 
 * 
Jose Fonseca's avatar
Jose Fonseca committed
35
 * @author Jose Fonseca <jfonseca@vmware.com>
36 37
 */

38 39
#ifndef U_DEBUG_H_
#define U_DEBUG_H_
40

José Fonseca's avatar
José Fonseca committed
41

Dylan Baker's avatar
Dylan Baker committed
42
#include "util/os_misc.h"
43

44 45 46 47 48
#if defined(PIPE_OS_HAIKU)
/* Haiku provides debug_printf in libroot with OS.h */
#include <OS.h>
#endif

49
#include "pipe/p_defines.h"
50

José Fonseca's avatar
José Fonseca committed
51

52 53 54 55 56
#ifdef	__cplusplus
extern "C" {
#endif


57 58 59 60 61
#if defined(__GNUC__)
#define _util_printf_format(fmt, list) __attribute__ ((format (printf, fmt, list)))
#else
#define _util_printf_format(fmt, list)
#endif
62

José Fonseca's avatar
José Fonseca committed
63 64 65
void _debug_vprintf(const char *format, va_list ap);
   

66
static inline void
José Fonseca's avatar
José Fonseca committed
67 68 69 70 71 72 73 74 75
_debug_printf(const char *format, ...)
{
   va_list ap;
   va_start(ap, format);
   _debug_vprintf(format, ap);
   va_end(ap);
}


76 77 78
/**
 * Print debug messages.
 *
79 80
 * The actual channel used to output debug message is platform specific. To
 * avoid misformating or truncation, follow these rules of thumb:
81
 * - output whole lines
82
 * - avoid outputing large strings (512 bytes is the current maximum length
83 84
 * that is guaranteed to be printed in all platforms)
 */
aljen's avatar
aljen committed
85
#if !defined(PIPE_OS_HAIKU)
86
static inline void
87 88
debug_printf(const char *format, ...) _util_printf_format(1,2);

89
static inline void
José Fonseca's avatar
José Fonseca committed
90 91 92 93 94 95 96
debug_printf(const char *format, ...)
{
#ifdef DEBUG
   va_list ap;
   va_start(ap, format);
   _debug_vprintf(format, ap);
   va_end(ap);
Brian's avatar
Brian committed
97 98
#else
   (void) format; /* silence warning */
José Fonseca's avatar
José Fonseca committed
99 100
#endif
}
101
#endif
José Fonseca's avatar
José Fonseca committed
102 103


Micah Dowty's avatar
Micah Dowty committed
104 105 106 107
/*
 * ... isn't portable so we need to pass arguments in parentheses.
 *
 * usage:
108
 *    debug_printf_once(("answer: %i\n", 42));
Micah Dowty's avatar
Micah Dowty committed
109 110 111 112 113 114 115 116 117 118 119
 */
#define debug_printf_once(args) \
   do { \
      static boolean once = TRUE; \
      if (once) { \
         once = FALSE; \
         debug_printf args; \
      } \
   } while (0)


José Fonseca's avatar
José Fonseca committed
120 121 122 123 124
#ifdef DEBUG
#define debug_vprintf(_format, _ap) _debug_vprintf(_format, _ap)
#else
#define debug_vprintf(_format, _ap) ((void)0)
#endif
José Fonseca's avatar
José Fonseca committed
125

126

127
#ifdef DEBUG
José Fonseca's avatar
José Fonseca committed
128 129 130
/**
 * Dump a blob in hex to the same place that debug_printf sends its
 * messages.
131
 */
132
void debug_print_blob( const char *name, const void *blob, unsigned size );
José Fonseca's avatar
José Fonseca committed
133 134 135 136 137
#else
#define debug_print_blob(_name, _blob, _size) ((void)0)
#endif


138 139 140 141 142 143 144 145 146
/**
 * Disable interactive error message boxes.
 *
 * Should be called as soon as possible for effectiveness.
 */
void
debug_disable_error_message_boxes(void);


147
/**
José Fonseca's avatar
José Fonseca committed
148
 * Hard-coded breakpoint.
149
 */
José Fonseca's avatar
José Fonseca committed
150
#ifdef DEBUG
151
#define debug_break() os_break()
José Fonseca's avatar
José Fonseca committed
152 153 154
#else /* !DEBUG */
#define debug_break() ((void)0)
#endif /* !DEBUG */
José Fonseca's avatar
José Fonseca committed
155

156

157 158 159
long
debug_get_num_option(const char *name, long dfault);

160 161 162
#ifdef _MSC_VER
__declspec(noreturn)
#endif
José Fonseca's avatar
José Fonseca committed
163 164 165
void _debug_assert_fail(const char *expr, 
                        const char *file, 
                        unsigned line, 
166
                        const char *function)
167 168
#if defined(__GNUC__) && !defined(DEBUG)
   __attribute__((noreturn))
169 170
#endif
;
José Fonseca's avatar
José Fonseca committed
171

José Fonseca's avatar
José Fonseca committed
172 173 174 175 176 177

/** 
 * Assert macro
 * 
 * Do not expect that the assert call terminates -- errors must be handled 
 * regardless of assert behavior.
178 179 180
 *
 * For non debug builds the assert macro will expand to a no-op, so do not
 * call functions with side effects in the assert expression.
José Fonseca's avatar
José Fonseca committed
181
 */
182
#ifndef NDEBUG
José Fonseca's avatar
José Fonseca committed
183
#define debug_assert(expr) ((expr) ? (void)0 : _debug_assert_fail(#expr, __FILE__, __LINE__, __FUNCTION__))
184
#else
185
#define debug_assert(expr) (void)(0 && (expr))
186 187 188
#endif


José Fonseca's avatar
José Fonseca committed
189
/** Override standard assert macro */
190 191 192 193 194 195
#ifdef assert
#undef assert
#endif
#define assert(expr) debug_assert(expr)


José Fonseca's avatar
José Fonseca committed
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
/**
 * Output the current function name.
 */
#ifdef DEBUG
#define debug_checkpoint() \
   _debug_printf("%s\n", __FUNCTION__)
#else
#define debug_checkpoint() \
   ((void)0) 
#endif


/**
 * Output the full source code position.
 */
#ifdef DEBUG
#define debug_checkpoint_full() \
213
   _debug_printf("%s:%u:%s\n", __FILE__, __LINE__, __FUNCTION__)
José Fonseca's avatar
José Fonseca committed
214 215 216 217 218 219 220 221 222
#else
#define debug_checkpoint_full() \
   ((void)0) 
#endif


/**
 * Output a warning message. Muted on release version.
 */
223 224
#ifdef DEBUG
#define debug_warning(__msg) \
José Fonseca's avatar
José Fonseca committed
225
   _debug_printf("%s:%u:%s: warning: %s\n", __FILE__, __LINE__, __FUNCTION__, __msg)
226 227 228 229 230 231
#else
#define debug_warning(__msg) \
   ((void)0) 
#endif


232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
/**
 * Emit a warning message, but only once.
 */
#ifdef DEBUG
#define debug_warn_once(__msg) \
   do { \
      static bool warned = FALSE; \
      if (!warned) { \
         _debug_printf("%s:%u:%s: one time warning: %s\n", \
                       __FILE__, __LINE__, __FUNCTION__, __msg); \
         warned = TRUE; \
      } \
   } while (0)
#else
#define debug_warn_once(__msg) \
   ((void)0) 
#endif


José Fonseca's avatar
José Fonseca committed
251 252 253 254 255
/**
 * Output an error message. Not muted on release version.
 */
#ifdef DEBUG
#define debug_error(__msg) \
José Fonseca's avatar
José Fonseca committed
256
   _debug_printf("%s:%u:%s: error: %s\n", __FILE__, __LINE__, __FUNCTION__, __msg) 
José Fonseca's avatar
José Fonseca committed
257 258
#else
#define debug_error(__msg) \
José Fonseca's avatar
José Fonseca committed
259
   _debug_printf("error: %s\n", __msg)
José Fonseca's avatar
José Fonseca committed
260 261
#endif

262 263 264 265 266
/**
 * Output a debug log message to the debug info callback.
 */
#define pipe_debug_message(cb, type, fmt, ...) do { \
   static unsigned id = 0; \
267 268 269 270 271
   if ((cb) && (cb)->debug_message) { \
      _pipe_debug_message(cb, &id, \
                          PIPE_DEBUG_TYPE_ ## type, \
                          fmt, ##__VA_ARGS__); \
   } \
272 273 274 275 276 277 278 279 280 281 282
} while (0)

struct pipe_debug_callback;

void
_pipe_debug_message(
   struct pipe_debug_callback *cb,
   unsigned *id,
   enum pipe_debug_type type,
   const char *fmt, ...) _util_printf_format(4, 5);

José Fonseca's avatar
José Fonseca committed
283

284 285 286 287 288 289
/**
 * Used by debug_dump_enum and debug_dump_flags to describe symbols.
 */
struct debug_named_value
{
   const char *name;
290
   uint64_t value;
291
   const char *desc;
292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313
};


/**
 * Some C pre-processor magic to simplify creating named values.
 * 
 * Example:
 * @code
 * static const debug_named_value my_names[] = {
 *    DEBUG_NAMED_VALUE(MY_ENUM_VALUE_X),
 *    DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Y),
 *    DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Z),
 *    DEBUG_NAMED_VALUE_END
 * };
 * 
 *    ...
 *    debug_printf("%s = %s\n", 
 *                 name,
 *                 debug_dump_enum(my_names, my_value));
 *    ...
 * @endcode
 */
314
#define DEBUG_NAMED_VALUE(__symbol) {#__symbol, (unsigned long)__symbol, NULL}
315 316
#define DEBUG_NAMED_VALUE_WITH_DESCRIPTION(__symbol, __desc) {#__symbol, (unsigned long)__symbol, __desc}
#define DEBUG_NAMED_VALUE_END {NULL, 0, NULL}
317 318 319 320 321 322 323 324 325


/**
 * Convert a enum value to a string.
 */
const char *
debug_dump_enum(const struct debug_named_value *names, 
                unsigned long value);

326 327 328 329 330
const char *
debug_dump_enum_noprefix(const struct debug_named_value *names, 
                         const char *prefix,
                         unsigned long value);

331 332 333 334 335 336 337 338 339

/**
 * Convert binary flags value to a string.
 */
const char *
debug_dump_flags(const struct debug_named_value *names, 
                 unsigned long value);


340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376
/**
 * Function enter exit loggers
 */
#ifdef DEBUG
int debug_funclog_enter(const char* f, const int line, const char* file);
void debug_funclog_exit(const char* f, const int line, const char* file);
void debug_funclog_enter_exit(const char* f, const int line, const char* file);

#define DEBUG_FUNCLOG_ENTER() \
   int __debug_decleration_work_around = \
      debug_funclog_enter(__FUNCTION__, __LINE__, __FILE__)
#define DEBUG_FUNCLOG_EXIT() \
   do { \
      (void)__debug_decleration_work_around; \
      debug_funclog_exit(__FUNCTION__, __LINE__, __FILE__); \
      return; \
   } while(0)
#define DEBUG_FUNCLOG_EXIT_RET(ret) \
   do { \
      (void)__debug_decleration_work_around; \
      debug_funclog_exit(__FUNCTION__, __LINE__, __FILE__); \
      return ret; \
   } while(0)
#define DEBUG_FUNCLOG_ENTER_EXIT() \
   debug_funclog_enter_exit(__FUNCTION__, __LINE__, __FILE__)

#else
#define DEBUG_FUNCLOG_ENTER() \
   int __debug_decleration_work_around
#define DEBUG_FUNCLOG_EXIT() \
   do { (void)__debug_decleration_work_around; return; } while(0)
#define DEBUG_FUNCLOG_EXIT_RET(ret) \
   do { (void)__debug_decleration_work_around; return ret; } while(0)
#define DEBUG_FUNCLOG_ENTER_EXIT()
#endif


377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395
/**
 * Get option.
 * 
 * It is an alias for getenv on Linux. 
 * 
 * On Windows it reads C:\gallium.cfg, which is a text file with CR+LF line 
 * endings with one option per line as
 *  
 *   NAME=value
 * 
 * This file must be terminated with an extra empty line.
 */
const char *
debug_get_option(const char *name, const char *dfault);

boolean
debug_get_bool_option(const char *name, boolean dfault);

long
396
debug_get_num_option(const char *name, long dfault);
397

398
uint64_t
399 400
debug_get_flags_option(const char *name, 
                       const struct debug_named_value *flags,
401
                       uint64_t dfault);
402

403 404 405 406 407 408 409 410 411 412 413 414 415
#define DEBUG_GET_ONCE_OPTION(suffix, name, dfault) \
static const char * \
debug_get_option_ ## suffix (void) \
{ \
   static boolean first = TRUE; \
   static const char * value; \
   if (first) { \
      first = FALSE; \
      value = debug_get_option(name, dfault); \
   } \
   return value; \
}

416 417 418 419 420 421
#define DEBUG_GET_ONCE_BOOL_OPTION(sufix, name, dfault) \
static boolean \
debug_get_option_ ## sufix (void) \
{ \
   static boolean first = TRUE; \
   static boolean value; \
422 423
   if (first) { \
      first = FALSE; \
424
      value = debug_get_bool_option(name, dfault); \
425
   } \
426 427 428 429 430 431 432 433 434
   return value; \
}

#define DEBUG_GET_ONCE_NUM_OPTION(sufix, name, dfault) \
static long \
debug_get_option_ ## sufix (void) \
{ \
   static boolean first = TRUE; \
   static long value; \
435 436
   if (first) { \
      first = FALSE; \
437
      value = debug_get_num_option(name, dfault); \
438
   } \
439 440 441 442 443 444 445 446 447
   return value; \
}

#define DEBUG_GET_ONCE_FLAGS_OPTION(sufix, name, flags, dfault) \
static unsigned long \
debug_get_option_ ## sufix (void) \
{ \
   static boolean first = TRUE; \
   static unsigned long value; \
448 449
   if (first) { \
      first = FALSE; \
450
      value = debug_get_flags_option(name, flags, dfault); \
451
   } \
452 453 454
   return value; \
}

455

456 457 458 459
#ifdef	__cplusplus
}
#endif

460
#endif /* U_DEBUG_H_ */