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 #ifdef DBG
  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 void _debug_vprintf(const char *format, va_list ap);
  64
  65
  66 static void INLINE
  67 _debug_printf(const char *format, ...)
  68 {
  69    va_list ap;
  70    va_start(ap, format);
  71    _debug_vprintf(format, ap);
  72    va_end(ap);
  73 }
  74
  75
  76 /**
  77  * Print debug messages.
  78  *
  79  * The actual channel used to output debug message is platform specific. To
  80  * 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  * that is guaranteed to be printed in all platforms)
  84  */
  85 static void INLINE
  86 debug_printf(const char *format, ...)
  87 {
  88 #ifdef DEBUG
  89    va_list ap;
  90    va_start(ap, format);
  91    _debug_vprintf(format, ap);
  92    va_end(ap);
  93 #endif
  94 }
  95
  96
  97 #ifdef DEBUG
  98 #define debug_vprintf(_format, _ap) _debug_vprintf(_format, _ap)
  99 #else
 100 #define debug_vprintf(_format, _ap) ((void)0)
 101 #endif
 102
 103
 104 /**
 105  * Dump a blob in hex to the same place that debug_printf sends its
 106  * messages.
 107  */
 108 #ifdef DEBUG
 109 void debug_print_blob( const char *name,
 110                        const void *blob,
 111                        unsigned size );
 112 #else
 113 #define debug_print_blob(_name, _blob, _size) ((void)0)
 114 #endif
 115
 116
 117 void _debug_break(void);
 118
 119
 120 /**
 121  * Hard-coded breakpoint.
 122  */
 123 #ifdef DEBUG
 124 #if (defined(__i386__) || defined(__386__)) && defined(__GNUC__)
 125 #define debug_break() __asm("int3")
 126 #elif (defined(__i386__) || defined(__386__)) && defined(__MSC__)
 127 #define debug_break()  _asm {int 3}
 128 #else
 129 #define debug_break() _debug_break()
 130 #endif
 131 #else /* !DEBUG */
 132 #define debug_break() ((void)0)
 133 #endif /* !DEBUG */
 134
 135
 136 void _debug_assert_fail(const char *expr,
 137                         const char *file,
 138                         unsigned line,
 139                         const char *function);
 140
 141
 142 /**
 143  * Assert macro
 144  *
 145  * Do not expect that the assert call terminates -- errors must be handled
 146  * regardless of assert behavior.
 147  */
 148 #ifdef DEBUG
 149 #define debug_assert(expr) ((expr) ? (void)0 : _debug_assert_fail(#expr, __FILE__, __LINE__, __FUNCTION__))
 150 #else
 151 #define debug_assert(expr) ((void)0)
 152 #endif
 153
 154
 155 /** Override standard assert macro */
 156 #ifdef assert
 157 #undef assert
 158 #endif
 159 #define assert(expr) debug_assert(expr)
 160
 161
 162 /**
 163  * Output the current function name.
 164  */
 165 #ifdef DEBUG
 166 #define debug_checkpoint() \
 167    _debug_printf("%s\n", __FUNCTION__)
 168 #else
 169 #define debug_checkpoint() \
 170    ((void)0)
 171 #endif
 172
 173
 174 /**
 175  * Output the full source code position.
 176  */
 177 #ifdef DEBUG
 178 #define debug_checkpoint_full() \
 179    debug_printf("%s:%u:%s", __FILE__, __LINE__, __FUNCTION__)
 180 #else
 181 #define debug_checkpoint_full() \
 182    ((void)0)
 183 #endif
 184
 185
 186 /**
 187  * Output a warning message. Muted on release version.
 188  */
 189 #ifdef DEBUG
 190 #define debug_warning(__msg) \
 191    _debug_printf("%s:%u:%s: warning: %s\n", __FILE__, __LINE__, __FUNCTION__, (__msg))
 192 #else
 193 #define debug_warning(__msg) \
 194    ((void)0)
 195 #endif
 196
 197
 198 /**
 199  * Output an error message. Not muted on release version.
 200  */
 201 #ifdef DEBUG
 202 #define debug_error(__msg) \
 203    _debug_printf("%s:%u:%s: error: %s\n", __FILE__, __LINE__, __FUNCTION__, (__msg))
 204 #else
 205 #define debug_error(__msg) \
 206    _debug_printf("error: %s\n", __msg))
 207 #endif
 208
 209
 210 /**
 211  * Used by debug_dump_enum and debug_dump_flags to describe symbols.
 212  */
 213 struct debug_named_value
 214 {
 215    const char *name;
 216    unsigned long value;
 217 };
 218
 219
 220 /**
 221  * Some C pre-processor magic to simplify creating named values.
 222  *
 223  * Example:
 224  * @code
 225  * static const debug_named_value my_names[] = {
 226  *    DEBUG_NAMED_VALUE(MY_ENUM_VALUE_X),
 227  *    DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Y),
 228  *    DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Z),
 229  *    DEBUG_NAMED_VALUE_END
 230  * };
 231  *
 232  *    ...
 233  *    debug_printf("%s = %s\n",
 234  *                 name,
 235  *                 debug_dump_enum(my_names, my_value));
 236  *    ...
 237  * @endcode
 238  */
 239 #define DEBUG_NAMED_VALUE(__symbol) {#__symbol, (unsigned long)__symbol}
 240 #define DEBUG_NAMED_VALUE_END {NULL, 0}
 241
 242
 243 /**
 244  * Convert a enum value to a string.
 245  */
 246 const char *
 247 debug_dump_enum(const struct debug_named_value *names,
 248                 unsigned long value);
 249
 250
 251 /**
 252  * Convert binary flags value to a string.
 253  */
 254 const char *
 255 debug_dump_flags(const struct debug_named_value *names,
 256                  unsigned long value);
 257
 258
 259 /**
 260  * Get option.
 261  *
 262  * It is an alias for getenv on Linux.
 263  *
 264  * On Windows it reads C:\gallium.cfg, which is a text file with CR+LF line
 265  * endings with one option per line as
 266  *
 267  *   NAME=value
 268  *
 269  * This file must be terminated with an extra empty line.
 270  */
 271 const char *
 272 debug_get_option(const char *name, const char *dfault);
 273
 274 boolean
 275 debug_get_bool_option(const char *name, boolean dfault);
 276
 277 long
 278 debug_get_unsigned_option(const char *name, long dfault);
 279
 280 unsigned long
 281 debug_get_flags_option(const char *name,
 282                        const struct debug_named_value *flags,
 283                        unsigned long dfault);
 284
 285
 286 void *
 287 debug_malloc(const char *file, unsigned line, const char *function,
 288              size_t size);
 289
 290 void
 291 debug_free(const char *file, unsigned line, const char *function,
 292            void *ptr);
 293
 294 void *
 295 debug_calloc(const char *file, unsigned line, const char *function,
 296              size_t count, size_t size );
 297
 298 void *
 299 debug_realloc(const char *file, unsigned line, const char *function,
 300               void *old_ptr, size_t old_size, size_t new_size );
 301
 302 void
 303 debug_memory_reset(void);
 304
 305 void
 306 debug_memory_report(void);
 307
 308
 309 #ifdef  __cplusplus
 310 }
 311 #endif
 312
 313 #endif /* P_DEBUG_H_ */