src/gallium/include/pipe/p_debug.h

   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 P_DEBUG_H_
  39 #define P_DEBUG_H_
  40
  41
  42 #include <stdarg.h>
  43
  44 #include "p_compiler.h"
  45
  46
  47 #ifdef  __cplusplus
  48 extern "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
  69 void _debug_vprintf(const char *format, va_list ap);
  70
  71
  72 static 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  */
  91 static INLINE void
  92 debug_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  */
 117 void debug_print_blob( const char *name, const void *blob, unsigned size );
 118
 119 /* Print a message along with a prettified format string
 120  */
 121 void 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
 128 void _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
 147 long
 148 debug_get_num_option(const char *name, long dfault);
 149
 150 void _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  */
 227 struct 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  */
 260 const char *
 261 debug_dump_enum(const struct debug_named_value *names,
 262                 unsigned long value);
 263
 264
 265 /**
 266  * Convert binary flags value to a string.
 267  */
 268 const char *
 269 debug_dump_flags(const struct debug_named_value *names,
 270                  unsigned long value);
 271
 272
 273 /**
 274  * Get option.
 275  *
 276  * It is an alias for getenv on Linux.
 277  *
 278  * On Windows it reads C:\gallium.cfg, which is a text file with CR+LF line
 279  * endings with one option per line as
 280  *
 281  *   NAME=value
 282  *
 283  * This file must be terminated with an extra empty line.
 284  */
 285 const char *
 286 debug_get_option(const char *name, const char *dfault);
 287
 288 boolean
 289 debug_get_bool_option(const char *name, boolean dfault);
 290
 291 long
 292 debug_get_num_option(const char *name, long dfault);
 293
 294 unsigned long
 295 debug_get_flags_option(const char *name,
 296                        const struct debug_named_value *flags,
 297                        unsigned long dfault);
 298
 299
 300 void *
 301 debug_malloc(const char *file, unsigned line, const char *function,
 302              size_t size);
 303
 304 void
 305 debug_free(const char *file, unsigned line, const char *function,
 306            void *ptr);
 307
 308 void *
 309 debug_calloc(const char *file, unsigned line, const char *function,
 310              size_t count, size_t size );
 311
 312 void *
 313 debug_realloc(const char *file, unsigned line, const char *function,
 314               void *old_ptr, size_t old_size, size_t new_size );
 315
 316 unsigned long
 317 debug_memory_begin(void);
 318
 319 void
 320 debug_memory_end(unsigned long beginning);
 321
 322
 323 #if defined(PROFILE) && defined(PIPE_SUBSYSTEM_WINDOWS_DISPLAY)
 324
 325 void
 326 debug_profile_start(void);
 327
 328 void
 329 debug_profile_stop(void);
 330
 331 #endif
 332
 333
 334 #ifdef DEBUG
 335 struct pipe_surface;
 336 void debug_dump_image(const char *prefix,
 337                       unsigned format, unsigned cpp,
 338                       unsigned width, unsigned height,
 339                       unsigned stride,
 340                       const void *data);
 341 void debug_dump_surface(const char *prefix,
 342                         struct pipe_surface *surface);
 343 void debug_dump_surface_bmp(const char *filename,
 344                             struct pipe_surface *surface);
 345 #else
 346 #define debug_dump_image(prefix, format, cpp, width, height, stride, data) ((void)0)
 347 #define debug_dump_surface(prefix, surface) ((void)0)
 348 #define debug_dump_surface_bmp(filename, surface) ((void)0)
 349 #endif
 350
 351
 352 #ifdef  __cplusplus
 353 }
 354 #endif
 355
 356 #endif /* P_DEBUG_H_ */