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