1/************************************************************************** 2 * 3 * Copyright 2008 Tungsten Graphics, Inc., Cedar Park, Texas. 4 * All Rights Reserved. 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a 7 * copy of this software and associated documentation files (the 8 * "Software"), to deal in the Software without restriction, including 9 * without limitation the rights to use, copy, modify, merge, publish, 10 * distribute, sub license, and/or sell copies of the Software, and to 11 * permit persons to whom the Software is furnished to do so, subject to 12 * the following conditions: 13 * 14 * The above copyright notice and this permission notice (including the 15 * next paragraph) shall be included in all copies or substantial portions 16 * of the Software. 17 * 18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 19 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 20 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. 21 * IN NO EVENT SHALL TUNGSTEN GRAPHICS AND/OR ITS SUPPLIERS BE LIABLE FOR 22 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 23 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 24 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 25 * 26 **************************************************************************/ 27 28/** 29 * @file 30 * Cross-platform debugging helpers. 31 * 32 * For now it just has assert and printf replacements, but it might be extended 33 * with stack trace reports and more advanced logging in the near future. 34 * 35 * @author Jose Fonseca <jrfonseca@tungstengraphics.com> 36 */ 37 38#ifndef U_DEBUG_H_ 39#define U_DEBUG_H_ 40 41 42#include <assert.h> 43#include "os/os_misc.h" 44 45 46#ifdef __cplusplus 47extern "C" { 48#endif 49 50 51#if defined(__GNUC__) 52#define _util_printf_format(fmt, list) __attribute__ ((format (printf, fmt, list))) 53#else 54#define _util_printf_format(fmt, list) 55#endif 56 57void _debug_vprintf(const char *format, va_list ap); 58 59 60static INLINE void 61_debug_printf(const char *format, ...) 62{ 63 va_list ap; 64 va_start(ap, format); 65 _debug_vprintf(format, ap); 66 va_end(ap); 67} 68 69 70/** 71 * Print debug messages. 72 * 73 * The actual channel used to output debug message is platform specific. To 74 * avoid misformating or truncation, follow these rules of thumb: 75 * - output whole lines 76 * - avoid outputing large strings (512 bytes is the current maximum length 77 * that is guaranteed to be printed in all platforms) 78 */ 79#if !defined(PIPE_OS_HAIKU) 80static INLINE void 81debug_printf(const char *format, ...) _util_printf_format(1,2); 82 83static INLINE void 84debug_printf(const char *format, ...) 85{ 86#ifdef DEBUG 87 va_list ap; 88 va_start(ap, format); 89 _debug_vprintf(format, ap); 90 va_end(ap); 91#else 92 (void) format; /* silence warning */ 93#endif 94} 95#else /* is Haiku */ 96/* Haiku provides debug_printf in libroot with OS.h */ 97#include <OS.h> 98#endif 99 100 101/* 102 * ... isn't portable so we need to pass arguments in parentheses. 103 * 104 * usage: 105 * debug_printf_once(("answer: %i\n", 42)); 106 */ 107#define debug_printf_once(args) \ 108 do { \ 109 static boolean once = TRUE; \ 110 if (once) { \ 111 once = FALSE; \ 112 debug_printf args; \ 113 } \ 114 } while (0) 115 116 117#ifdef DEBUG 118#define debug_vprintf(_format, _ap) _debug_vprintf(_format, _ap) 119#else 120#define debug_vprintf(_format, _ap) ((void)0) 121#endif 122 123 124#ifdef DEBUG 125/** 126 * Dump a blob in hex to the same place that debug_printf sends its 127 * messages. 128 */ 129void debug_print_blob( const char *name, const void *blob, unsigned size ); 130 131/* Print a message along with a prettified format string 132 */ 133void debug_print_format(const char *msg, unsigned fmt ); 134#else 135#define debug_print_blob(_name, _blob, _size) ((void)0) 136#define debug_print_format(_msg, _fmt) ((void)0) 137#endif 138 139 140/** 141 * Hard-coded breakpoint. 142 */ 143#ifdef DEBUG 144#define debug_break() os_break() 145#else /* !DEBUG */ 146#define debug_break() ((void)0) 147#endif /* !DEBUG */ 148 149 150long 151debug_get_num_option(const char *name, long dfault); 152 153void _debug_assert_fail(const char *expr, 154 const char *file, 155 unsigned line, 156 const char *function); 157 158 159/** 160 * Assert macro 161 * 162 * Do not expect that the assert call terminates -- errors must be handled 163 * regardless of assert behavior. 164 * 165 * For non debug builds the assert macro will expand to a no-op, so do not 166 * call functions with side effects in the assert expression. 167 */ 168#ifdef DEBUG 169#define debug_assert(expr) ((expr) ? (void)0 : _debug_assert_fail(#expr, __FILE__, __LINE__, __FUNCTION__)) 170#else 171#define debug_assert(expr) do { } while (0 && (expr)) 172#endif 173 174 175/** Override standard assert macro */ 176#ifdef assert 177#undef assert 178#endif 179#define assert(expr) debug_assert(expr) 180 181 182/** 183 * Output the current function name. 184 */ 185#ifdef DEBUG 186#define debug_checkpoint() \ 187 _debug_printf("%s\n", __FUNCTION__) 188#else 189#define debug_checkpoint() \ 190 ((void)0) 191#endif 192 193 194/** 195 * Output the full source code position. 196 */ 197#ifdef DEBUG 198#define debug_checkpoint_full() \ 199 _debug_printf("%s:%u:%s\n", __FILE__, __LINE__, __FUNCTION__) 200#else 201#define debug_checkpoint_full() \ 202 ((void)0) 203#endif 204 205 206/** 207 * Output a warning message. Muted on release version. 208 */ 209#ifdef DEBUG 210#define debug_warning(__msg) \ 211 _debug_printf("%s:%u:%s: warning: %s\n", __FILE__, __LINE__, __FUNCTION__, __msg) 212#else 213#define debug_warning(__msg) \ 214 ((void)0) 215#endif 216 217 218/** 219 * Emit a warning message, but only once. 220 */ 221#ifdef DEBUG 222#define debug_warn_once(__msg) \ 223 do { \ 224 static bool warned = FALSE; \ 225 if (!warned) { \ 226 _debug_printf("%s:%u:%s: one time warning: %s\n", \ 227 __FILE__, __LINE__, __FUNCTION__, __msg); \ 228 warned = TRUE; \ 229 } \ 230 } while (0) 231#else 232#define debug_warn_once(__msg) \ 233 ((void)0) 234#endif 235 236 237/** 238 * Output an error message. Not muted on release version. 239 */ 240#ifdef DEBUG 241#define debug_error(__msg) \ 242 _debug_printf("%s:%u:%s: error: %s\n", __FILE__, __LINE__, __FUNCTION__, __msg) 243#else 244#define debug_error(__msg) \ 245 _debug_printf("error: %s\n", __msg) 246#endif 247 248 249/** 250 * Used by debug_dump_enum and debug_dump_flags to describe symbols. 251 */ 252struct debug_named_value 253{ 254 const char *name; 255 unsigned long value; 256 const char *desc; 257}; 258 259 260/** 261 * Some C pre-processor magic to simplify creating named values. 262 * 263 * Example: 264 * @code 265 * static const debug_named_value my_names[] = { 266 * DEBUG_NAMED_VALUE(MY_ENUM_VALUE_X), 267 * DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Y), 268 * DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Z), 269 * DEBUG_NAMED_VALUE_END 270 * }; 271 * 272 * ... 273 * debug_printf("%s = %s\n", 274 * name, 275 * debug_dump_enum(my_names, my_value)); 276 * ... 277 * @endcode 278 */ 279#define DEBUG_NAMED_VALUE(__symbol) DEBUG_NAMED_VALUE_WITH_DESCRIPTION(__symbol, NULL) 280#define DEBUG_NAMED_VALUE_WITH_DESCRIPTION(__symbol, __desc) {#__symbol, (unsigned long)__symbol, __desc} 281#define DEBUG_NAMED_VALUE_END {NULL, 0, NULL} 282 283 284/** 285 * Convert a enum value to a string. 286 */ 287const char * 288debug_dump_enum(const struct debug_named_value *names, 289 unsigned long value); 290 291const char * 292debug_dump_enum_noprefix(const struct debug_named_value *names, 293 const char *prefix, 294 unsigned long value); 295 296 297/** 298 * Convert binary flags value to a string. 299 */ 300const char * 301debug_dump_flags(const struct debug_named_value *names, 302 unsigned long value); 303 304 305/** 306 * Function enter exit loggers 307 */ 308#ifdef DEBUG 309int debug_funclog_enter(const char* f, const int line, const char* file); 310void debug_funclog_exit(const char* f, const int line, const char* file); 311void debug_funclog_enter_exit(const char* f, const int line, const char* file); 312 313#define DEBUG_FUNCLOG_ENTER() \ 314 int __debug_decleration_work_around = \ 315 debug_funclog_enter(__FUNCTION__, __LINE__, __FILE__) 316#define DEBUG_FUNCLOG_EXIT() \ 317 do { \ 318 (void)__debug_decleration_work_around; \ 319 debug_funclog_exit(__FUNCTION__, __LINE__, __FILE__); \ 320 return; \ 321 } while(0) 322#define DEBUG_FUNCLOG_EXIT_RET(ret) \ 323 do { \ 324 (void)__debug_decleration_work_around; \ 325 debug_funclog_exit(__FUNCTION__, __LINE__, __FILE__); \ 326 return ret; \ 327 } while(0) 328#define DEBUG_FUNCLOG_ENTER_EXIT() \ 329 debug_funclog_enter_exit(__FUNCTION__, __LINE__, __FILE__) 330 331#else 332#define DEBUG_FUNCLOG_ENTER() \ 333 int __debug_decleration_work_around 334#define DEBUG_FUNCLOG_EXIT() \ 335 do { (void)__debug_decleration_work_around; return; } while(0) 336#define DEBUG_FUNCLOG_EXIT_RET(ret) \ 337 do { (void)__debug_decleration_work_around; return ret; } while(0) 338#define DEBUG_FUNCLOG_ENTER_EXIT() 339#endif 340 341 342/** 343 * Get option. 344 * 345 * It is an alias for getenv on Linux. 346 * 347 * On Windows it reads C:\gallium.cfg, which is a text file with CR+LF line 348 * endings with one option per line as 349 * 350 * NAME=value 351 * 352 * This file must be terminated with an extra empty line. 353 */ 354const char * 355debug_get_option(const char *name, const char *dfault); 356 357boolean 358debug_get_bool_option(const char *name, boolean dfault); 359 360long 361debug_get_num_option(const char *name, long dfault); 362 363unsigned long 364debug_get_flags_option(const char *name, 365 const struct debug_named_value *flags, 366 unsigned long dfault); 367 368#define DEBUG_GET_ONCE_BOOL_OPTION(sufix, name, dfault) \ 369static boolean \ 370debug_get_option_ ## sufix (void) \ 371{ \ 372 static boolean first = TRUE; \ 373 static boolean value; \ 374 if (first) { \ 375 first = FALSE; \ 376 value = debug_get_bool_option(name, dfault); \ 377 } \ 378 return value; \ 379} 380 381#define DEBUG_GET_ONCE_NUM_OPTION(sufix, name, dfault) \ 382static long \ 383debug_get_option_ ## sufix (void) \ 384{ \ 385 static boolean first = TRUE; \ 386 static long value; \ 387 if (first) { \ 388 first = FALSE; \ 389 value = debug_get_num_option(name, dfault); \ 390 } \ 391 return value; \ 392} 393 394#define DEBUG_GET_ONCE_FLAGS_OPTION(sufix, name, flags, dfault) \ 395static unsigned long \ 396debug_get_option_ ## sufix (void) \ 397{ \ 398 static boolean first = TRUE; \ 399 static unsigned long value; \ 400 if (first) { \ 401 first = FALSE; \ 402 value = debug_get_flags_option(name, flags, dfault); \ 403 } \ 404 return value; \ 405} 406 407 408unsigned long 409debug_memory_begin(void); 410 411void 412debug_memory_end(unsigned long beginning); 413 414 415#ifdef DEBUG 416struct pipe_context; 417struct pipe_surface; 418struct pipe_transfer; 419struct pipe_resource; 420 421void debug_dump_image(const char *prefix, 422 unsigned format, unsigned cpp, 423 unsigned width, unsigned height, 424 unsigned stride, 425 const void *data); 426void debug_dump_surface(struct pipe_context *pipe, 427 const char *prefix, 428 struct pipe_surface *surface); 429void debug_dump_texture(struct pipe_context *pipe, 430 const char *prefix, 431 struct pipe_resource *texture); 432void debug_dump_surface_bmp(struct pipe_context *pipe, 433 const char *filename, 434 struct pipe_surface *surface); 435void debug_dump_transfer_bmp(struct pipe_context *pipe, 436 const char *filename, 437 struct pipe_transfer *transfer); 438void debug_dump_float_rgba_bmp(const char *filename, 439 unsigned width, unsigned height, 440 float *rgba, unsigned stride); 441#else 442#define debug_dump_image(prefix, format, cpp, width, height, stride, data) ((void)0) 443#define debug_dump_surface(pipe, prefix, surface) ((void)0) 444#define debug_dump_surface_bmp(pipe, filename, surface) ((void)0) 445#define debug_dump_transfer_bmp(filename, transfer) ((void)0) 446#define debug_dump_float_rgba_bmp(filename, width, height, rgba, stride) ((void)0) 447#endif 448 449 450#ifdef __cplusplus 451} 452#endif 453 454#endif /* U_DEBUG_H_ */ 455