u_debug.h revision ea4bf267e4b023b08043f91ac44592fed1736e7f
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 69void _debug_vprintf(const char *format, va_list ap); 70 71 72static INLINE void 73_debug_printf(const char *format, ...) 74{ 75 va_list ap; 76 va_start(ap, format); 77 _debug_vprintf(format, ap); 78 va_end(ap); 79} 80 81 82/** 83 * Print debug messages. 84 * 85 * The actual channel used to output debug message is platform specific. To 86 * avoid misformating or truncation, follow these rules of thumb: 87 * - output whole lines 88 * - avoid outputing large strings (512 bytes is the current maximum length 89 * that is guaranteed to be printed in all platforms) 90 */ 91static INLINE void 92debug_printf(const char *format, ...) 93{ 94#ifdef DEBUG 95 va_list ap; 96 va_start(ap, format); 97 _debug_vprintf(format, ap); 98 va_end(ap); 99#else 100 (void) format; /* silence warning */ 101#endif 102} 103 104 105#ifdef DEBUG 106#define debug_vprintf(_format, _ap) _debug_vprintf(_format, _ap) 107#else 108#define debug_vprintf(_format, _ap) ((void)0) 109#endif 110 111 112#ifdef DEBUG 113/** 114 * Dump a blob in hex to the same place that debug_printf sends its 115 * messages. 116 */ 117void debug_print_blob( const char *name, const void *blob, unsigned size ); 118 119/* Print a message along with a prettified format string 120 */ 121void debug_print_format(const char *msg, unsigned fmt ); 122#else 123#define debug_print_blob(_name, _blob, _size) ((void)0) 124#define debug_print_format(_msg, _fmt) ((void)0) 125#endif 126 127 128void _debug_break(void); 129 130 131/** 132 * Hard-coded breakpoint. 133 */ 134#ifdef DEBUG 135#if defined(PIPE_ARCH_X86) && defined(PIPE_CC_GCC) 136#define debug_break() __asm("int3") 137#elif defined(PIPE_ARCH_X86) && defined(PIPE_CC_MSVC) 138#define debug_break() do { _asm {int 3} } while(0) 139#else 140#define debug_break() _debug_break() 141#endif 142#else /* !DEBUG */ 143#define debug_break() ((void)0) 144#endif /* !DEBUG */ 145 146 147long 148debug_get_num_option(const char *name, long dfault); 149 150void _debug_assert_fail(const char *expr, 151 const char *file, 152 unsigned line, 153 const char *function); 154 155 156/** 157 * Assert macro 158 * 159 * Do not expect that the assert call terminates -- errors must be handled 160 * regardless of assert behavior. 161 */ 162#ifdef DEBUG 163#define debug_assert(expr) ((expr) ? (void)0 : _debug_assert_fail(#expr, __FILE__, __LINE__, __FUNCTION__)) 164#else 165#define debug_assert(expr) ((void)0) 166#endif 167 168 169/** Override standard assert macro */ 170#ifdef assert 171#undef assert 172#endif 173#define assert(expr) debug_assert(expr) 174 175 176/** 177 * Output the current function name. 178 */ 179#ifdef DEBUG 180#define debug_checkpoint() \ 181 _debug_printf("%s\n", __FUNCTION__) 182#else 183#define debug_checkpoint() \ 184 ((void)0) 185#endif 186 187 188/** 189 * Output the full source code position. 190 */ 191#ifdef DEBUG 192#define debug_checkpoint_full() \ 193 _debug_printf("%s:%u:%s", __FILE__, __LINE__, __FUNCTION__) 194#else 195#define debug_checkpoint_full() \ 196 ((void)0) 197#endif 198 199 200/** 201 * Output a warning message. Muted on release version. 202 */ 203#ifdef DEBUG 204#define debug_warning(__msg) \ 205 _debug_printf("%s:%u:%s: warning: %s\n", __FILE__, __LINE__, __FUNCTION__, __msg) 206#else 207#define debug_warning(__msg) \ 208 ((void)0) 209#endif 210 211 212/** 213 * Output an error message. Not muted on release version. 214 */ 215#ifdef DEBUG 216#define debug_error(__msg) \ 217 _debug_printf("%s:%u:%s: error: %s\n", __FILE__, __LINE__, __FUNCTION__, __msg) 218#else 219#define debug_error(__msg) \ 220 _debug_printf("error: %s\n", __msg) 221#endif 222 223 224/** 225 * Used by debug_dump_enum and debug_dump_flags to describe symbols. 226 */ 227struct debug_named_value 228{ 229 const char *name; 230 unsigned long value; 231}; 232 233 234/** 235 * Some C pre-processor magic to simplify creating named values. 236 * 237 * Example: 238 * @code 239 * static const debug_named_value my_names[] = { 240 * DEBUG_NAMED_VALUE(MY_ENUM_VALUE_X), 241 * DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Y), 242 * DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Z), 243 * DEBUG_NAMED_VALUE_END 244 * }; 245 * 246 * ... 247 * debug_printf("%s = %s\n", 248 * name, 249 * debug_dump_enum(my_names, my_value)); 250 * ... 251 * @endcode 252 */ 253#define DEBUG_NAMED_VALUE(__symbol) {#__symbol, (unsigned long)__symbol} 254#define DEBUG_NAMED_VALUE_END {NULL, 0} 255 256 257/** 258 * Convert a enum value to a string. 259 */ 260const char * 261debug_dump_enum(const struct debug_named_value *names, 262 unsigned long value); 263 264const char * 265debug_dump_enum_noprefix(const struct debug_named_value *names, 266 const char *prefix, 267 unsigned long value); 268 269 270/** 271 * Convert binary flags value to a string. 272 */ 273const char * 274debug_dump_flags(const struct debug_named_value *names, 275 unsigned long value); 276 277 278/** 279 * Get option. 280 * 281 * It is an alias for getenv on Linux. 282 * 283 * On Windows it reads C:\gallium.cfg, which is a text file with CR+LF line 284 * endings with one option per line as 285 * 286 * NAME=value 287 * 288 * This file must be terminated with an extra empty line. 289 */ 290const char * 291debug_get_option(const char *name, const char *dfault); 292 293boolean 294debug_get_bool_option(const char *name, boolean dfault); 295 296long 297debug_get_num_option(const char *name, long dfault); 298 299unsigned long 300debug_get_flags_option(const char *name, 301 const struct debug_named_value *flags, 302 unsigned long dfault); 303 304 305void * 306debug_malloc(const char *file, unsigned line, const char *function, 307 size_t size); 308 309void 310debug_free(const char *file, unsigned line, const char *function, 311 void *ptr); 312 313void * 314debug_calloc(const char *file, unsigned line, const char *function, 315 size_t count, size_t size ); 316 317void * 318debug_realloc(const char *file, unsigned line, const char *function, 319 void *old_ptr, size_t old_size, size_t new_size ); 320 321unsigned long 322debug_memory_begin(void); 323 324void 325debug_memory_end(unsigned long beginning); 326 327 328#if defined(PROFILE) && defined(PIPE_SUBSYSTEM_WINDOWS_DISPLAY) 329 330void 331debug_profile_start(void); 332 333void 334debug_profile_stop(void); 335 336#endif 337 338 339#ifdef DEBUG 340struct pipe_surface; 341void debug_dump_image(const char *prefix, 342 unsigned format, unsigned cpp, 343 unsigned width, unsigned height, 344 unsigned stride, 345 const void *data); 346void debug_dump_surface(const char *prefix, 347 struct pipe_surface *surface); 348void debug_dump_surface_bmp(const char *filename, 349 struct pipe_surface *surface); 350#else 351#define debug_dump_image(prefix, format, cpp, width, height, stride, data) ((void)0) 352#define debug_dump_surface(prefix, surface) ((void)0) 353#define debug_dump_surface_bmp(filename, surface) ((void)0) 354#endif 355 356 357#ifdef __cplusplus 358} 359#endif 360 361#endif /* U_DEBUG_H_ */ 362