u_debug.h revision 4f5675e94b936d012b89937aac8a16c28143d5ec
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 <stdarg.h> 43 44#include "pipe/p_compiler.h" 45 46 47#ifdef __cplusplus 48extern "C" { 49#endif 50 51 52#if defined(DBG) || defined(DEBUG) 53#ifndef DEBUG 54#define DEBUG 1 55#endif 56#else 57#ifndef NDEBUG 58#define NDEBUG 1 59#endif 60#endif 61 62 63/* MSVC bebore VC7 does not have the __FUNCTION__ macro */ 64#if defined(_MSC_VER) && _MSC_VER < 1300 65#define __FUNCTION__ "???" 66#endif 67 68#if defined(__GNUC__) 69#define _util_printf_format(fmt, list) __attribute__ ((format (printf, fmt, list))) 70#else 71#define _util_printf_format(fmt, list) 72#endif 73 74void _debug_vprintf(const char *format, va_list ap); 75 76 77static INLINE void 78_debug_printf(const char *format, ...) 79{ 80 va_list ap; 81 va_start(ap, format); 82 _debug_vprintf(format, ap); 83 va_end(ap); 84} 85 86 87/** 88 * Print debug messages. 89 * 90 * The actual channel used to output debug message is platform specific. To 91 * avoid misformating or truncation, follow these rules of thumb: 92 * - output whole lines 93 * - avoid outputing large strings (512 bytes is the current maximum length 94 * that is guaranteed to be printed in all platforms) 95 */ 96#if !defined(PIPE_OS_HAIKU) 97static INLINE void 98debug_printf(const char *format, ...) _util_printf_format(1,2); 99 100static INLINE void 101debug_printf(const char *format, ...) 102{ 103#ifdef DEBUG 104 va_list ap; 105 va_start(ap, format); 106 _debug_vprintf(format, ap); 107 va_end(ap); 108#else 109 (void) format; /* silence warning */ 110#endif 111} 112 113#endif /* !PIPE_OS_HAIKU */ 114 115/* 116 * ... isn't portable so we need to pass arguments in parentheses. 117 * 118 * usage: 119 * debug_printf_once(("awnser: %i\n", 42)); 120 */ 121#define debug_printf_once(args) \ 122 do { \ 123 static boolean once = TRUE; \ 124 if (once) { \ 125 once = FALSE; \ 126 debug_printf args; \ 127 } \ 128 } while (0) 129 130 131#ifdef DEBUG 132#define debug_vprintf(_format, _ap) _debug_vprintf(_format, _ap) 133#else 134#define debug_vprintf(_format, _ap) ((void)0) 135#endif 136 137 138#ifdef DEBUG 139/** 140 * Dump a blob in hex to the same place that debug_printf sends its 141 * messages. 142 */ 143void debug_print_blob( const char *name, const void *blob, unsigned size ); 144 145/* Print a message along with a prettified format string 146 */ 147void debug_print_format(const char *msg, unsigned fmt ); 148#else 149#define debug_print_blob(_name, _blob, _size) ((void)0) 150#define debug_print_format(_msg, _fmt) ((void)0) 151#endif 152 153 154/** 155 * Hard-coded breakpoint. 156 */ 157#ifdef DEBUG 158#if (defined(PIPE_ARCH_X86) || defined(PIPE_ARCH_X86_64)) && defined(PIPE_CC_GCC) 159#define debug_break() __asm("int3") 160#elif defined(PIPE_CC_MSVC) 161#define debug_break() __debugbreak() 162#else 163void debug_break(void); 164#endif 165#else /* !DEBUG */ 166#define debug_break() ((void)0) 167#endif /* !DEBUG */ 168 169 170long 171debug_get_num_option(const char *name, long dfault); 172 173void _debug_assert_fail(const char *expr, 174 const char *file, 175 unsigned line, 176 const char *function); 177 178 179/** 180 * Assert macro 181 * 182 * Do not expect that the assert call terminates -- errors must be handled 183 * regardless of assert behavior. 184 * 185 * For non debug builds the assert macro will expand to a no-op, so do not 186 * call functions with side effects in the assert expression. 187 */ 188#ifdef DEBUG 189#define debug_assert(expr) ((expr) ? (void)0 : _debug_assert_fail(#expr, __FILE__, __LINE__, __FUNCTION__)) 190#else 191#define debug_assert(expr) do { } while (0 && (expr)) 192#endif 193 194 195/** Override standard assert macro */ 196#ifdef assert 197#undef assert 198#endif 199#define assert(expr) debug_assert(expr) 200 201 202/** 203 * Output the current function name. 204 */ 205#ifdef DEBUG 206#define debug_checkpoint() \ 207 _debug_printf("%s\n", __FUNCTION__) 208#else 209#define debug_checkpoint() \ 210 ((void)0) 211#endif 212 213 214/** 215 * Output the full source code position. 216 */ 217#ifdef DEBUG 218#define debug_checkpoint_full() \ 219 _debug_printf("%s:%u:%s", __FILE__, __LINE__, __FUNCTION__) 220#else 221#define debug_checkpoint_full() \ 222 ((void)0) 223#endif 224 225 226/** 227 * Output a warning message. Muted on release version. 228 */ 229#ifdef DEBUG 230#define debug_warning(__msg) \ 231 _debug_printf("%s:%u:%s: warning: %s\n", __FILE__, __LINE__, __FUNCTION__, __msg) 232#else 233#define debug_warning(__msg) \ 234 ((void)0) 235#endif 236 237 238/** 239 * Output an error message. Not muted on release version. 240 */ 241#ifdef DEBUG 242#define debug_error(__msg) \ 243 _debug_printf("%s:%u:%s: error: %s\n", __FILE__, __LINE__, __FUNCTION__, __msg) 244#else 245#define debug_error(__msg) \ 246 _debug_printf("error: %s\n", __msg) 247#endif 248 249 250/** 251 * Used by debug_dump_enum and debug_dump_flags to describe symbols. 252 */ 253struct debug_named_value 254{ 255 const char *name; 256 unsigned long value; 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) {#__symbol, (unsigned long)__symbol} 280#define DEBUG_NAMED_VALUE_END {NULL, 0} 281 282 283/** 284 * Convert a enum value to a string. 285 */ 286const char * 287debug_dump_enum(const struct debug_named_value *names, 288 unsigned long value); 289 290const char * 291debug_dump_enum_noprefix(const struct debug_named_value *names, 292 const char *prefix, 293 unsigned long value); 294 295 296/** 297 * Convert binary flags value to a string. 298 */ 299const char * 300debug_dump_flags(const struct debug_named_value *names, 301 unsigned long value); 302 303 304/** 305 * Get option. 306 * 307 * It is an alias for getenv on Linux. 308 * 309 * On Windows it reads C:\gallium.cfg, which is a text file with CR+LF line 310 * endings with one option per line as 311 * 312 * NAME=value 313 * 314 * This file must be terminated with an extra empty line. 315 */ 316const char * 317debug_get_option(const char *name, const char *dfault); 318 319boolean 320debug_get_bool_option(const char *name, boolean dfault); 321 322long 323debug_get_num_option(const char *name, long dfault); 324 325unsigned long 326debug_get_flags_option(const char *name, 327 const struct debug_named_value *flags, 328 unsigned long dfault); 329 330 331void * 332debug_malloc(const char *file, unsigned line, const char *function, 333 size_t size); 334 335void 336debug_free(const char *file, unsigned line, const char *function, 337 void *ptr); 338 339void * 340debug_calloc(const char *file, unsigned line, const char *function, 341 size_t count, size_t size ); 342 343void * 344debug_realloc(const char *file, unsigned line, const char *function, 345 void *old_ptr, size_t old_size, size_t new_size ); 346 347unsigned long 348debug_memory_begin(void); 349 350void 351debug_memory_end(unsigned long beginning); 352 353 354#ifdef DEBUG 355struct pipe_surface; 356struct pipe_transfer; 357struct pipe_texture; 358 359void debug_dump_image(const char *prefix, 360 unsigned format, unsigned cpp, 361 unsigned width, unsigned height, 362 unsigned stride, 363 const void *data); 364void debug_dump_surface(const char *prefix, 365 struct pipe_surface *surface); 366void debug_dump_texture(const char *prefix, 367 struct pipe_texture *texture); 368void debug_dump_surface_bmp(const char *filename, 369 struct pipe_surface *surface); 370void debug_dump_transfer_bmp(const char *filename, 371 struct pipe_transfer *transfer); 372void debug_dump_float_rgba_bmp(const char *filename, 373 unsigned width, unsigned height, 374 float *rgba, unsigned stride); 375#else 376#define debug_dump_image(prefix, format, cpp, width, height, stride, data) ((void)0) 377#define debug_dump_surface(prefix, surface) ((void)0) 378#define debug_dump_surface_bmp(filename, surface) ((void)0) 379#define debug_dump_transfer_bmp(filename, transfer) ((void)0) 380#define debug_dump_rgba_float_bmp(filename, width, height, rgba, stride) ((void)0) 381#endif 382 383 384#ifdef __cplusplus 385} 386#endif 387 388#endif /* U_DEBUG_H_ */ 389