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