u_debug.h revision 6b424a0550a5196818641857974f4cb04d61b933
1ec3ed6a5ebf6f2c406d7bcf94b6bc34fcaeb976eepoger@google.com/************************************************************************** 2ec3ed6a5ebf6f2c406d7bcf94b6bc34fcaeb976eepoger@google.com * 3ec3ed6a5ebf6f2c406d7bcf94b6bc34fcaeb976eepoger@google.com * Copyright 2008 Tungsten Graphics, Inc., Cedar Park, Texas. 4ec3ed6a5ebf6f2c406d7bcf94b6bc34fcaeb976eepoger@google.com * All Rights Reserved. 5ec3ed6a5ebf6f2c406d7bcf94b6bc34fcaeb976eepoger@google.com * 6ec3ed6a5ebf6f2c406d7bcf94b6bc34fcaeb976eepoger@google.com * Permission is hereby granted, free of charge, to any person obtaining a 7ec3ed6a5ebf6f2c406d7bcf94b6bc34fcaeb976eepoger@google.com * copy of this software and associated documentation files (the 84868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * "Software"), to deal in the Software without restriction, including 9b7061176c7f414616fe2e79e832b3e0abe326af6robertphillips@google.com * without limitation the rights to use, copy, modify, merge, publish, 104868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * distribute, sub license, and/or sell copies of the Software, and to 114868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * permit persons to whom the Software is furnished to do so, subject to 124868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * the following conditions: 134868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * 144868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * The above copyright notice and this permission notice (including the 154868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * next paragraph) shall be included in all copies or substantial portions 16e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * of the Software. 17e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * 18e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 19e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 20e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. 21e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * IN NO EVENT SHALL TUNGSTEN GRAPHICS AND/OR ITS SUPPLIERS BE LIABLE FOR 22e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 23e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 24e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 254868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * 26e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com **************************************************************************/ 274868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org 284868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org/** 29e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * @file 30e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * Cross-platform debugging helpers. 314868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * 3248dd1a26ec07c5baa04856202e4e7e2a53e4d7e5bsalomon@google.com * For now it just has assert and printf replacements, but it might be extended 334868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * with stack trace reports and more advanced logging in the near future. 34e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * 35e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * @author Jose Fonseca <jrfonseca@tungstengraphics.com> 364868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org */ 374868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org 384868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org#ifndef U_DEBUG_H_ 39a90c6803865766d28e92091f56f718f5e41fe80fcommit-bot@chromium.org#define U_DEBUG_H_ 40a90c6803865766d28e92091f56f718f5e41fe80fcommit-bot@chromium.org 41a90c6803865766d28e92091f56f718f5e41fe80fcommit-bot@chromium.org 42a90c6803865766d28e92091f56f718f5e41fe80fcommit-bot@chromium.org#include "os/os_misc.h" 434868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org 444868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org 454868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org#ifdef __cplusplus 464868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.orgextern "C" { 474868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org#endif 48f539318f0d3dba743ec1886d5d9df0fb1be628a1tfarina 494868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org 504868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org#if defined(__GNUC__) 514868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org#define _util_printf_format(fmt, list) __attribute__ ((format (printf, fmt, list))) 524868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org#else 534868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org#define _util_printf_format(fmt, list) 5473cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org#endif 5573cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org 5673cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.orgvoid _debug_vprintf(const char *format, va_list ap); 5773cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org 5873cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org 5973cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.orgstatic INLINE void 604868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org_debug_printf(const char *format, ...) 614868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org{ 6273cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org va_list ap; 6373cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org va_start(ap, format); 6473cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org _debug_vprintf(format, ap); 6573cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org va_end(ap); 6673cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org} 674868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org 684868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org 6973cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org/** 7073cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org * Print debug messages. 7173cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org * 7273cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org * The actual channel used to output debug message is platform specific. To 7373cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org * avoid misformating or truncation, follow these rules of thumb: 7473cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org * - output whole lines 754868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * - avoid outputing large strings (512 bytes is the current maximum length 764868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * that is guaranteed to be printed in all platforms) 7773cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org */ 7873cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org#if !defined(PIPE_OS_HAIKU) 7973cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.orgstatic INLINE void 8073cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.orgdebug_printf(const char *format, ...) _util_printf_format(1,2); 8173cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org 8273cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.orgstatic INLINE void 834868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.orgdebug_printf(const char *format, ...) 844868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org{ 8573cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org#ifdef DEBUG 8673cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org va_list ap; 8773cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org va_start(ap, format); 8873cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org _debug_vprintf(format, ap); 8973cb15351f33459e0c861a96135c634dec77ef9dcommit-bot@chromium.org va_end(ap); 904868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org#else 914868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org (void) format; /* silence warning */ 92e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com#endif 93e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com} 94e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com 95e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com#endif /* !PIPE_OS_HAIKU */ 96e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com 97e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com/* 987c545bddf806fc1b2e9ce61a9888b49d60471d73junov@chromium.org * ... isn't portable so we need to pass arguments in parentheses. 99e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * 100e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * usage: 101e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com * debug_printf_once(("awnser: %i\n", 42)); 102e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com */ 103e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com#define debug_printf_once(args) \ 104e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com do { \ 105e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com static boolean once = TRUE; \ 106e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com if (once) { \ 107e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com once = FALSE; \ 108ffe39bd3b66eb5090684959e7f2409346ab72d93tomhudson@google.com debug_printf args; \ 109e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com } \ 110e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com } while (0) 111e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com 1124868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org 113e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com#ifdef DEBUG 114e3605d0e748c1f79089f1e762f57e2a7d6644aa2reed@google.com#define debug_vprintf(_format, _ap) _debug_vprintf(_format, _ap) 1157c545bddf806fc1b2e9ce61a9888b49d60471d73junov@chromium.org#else 1167c545bddf806fc1b2e9ce61a9888b49d60471d73junov@chromium.org#define debug_vprintf(_format, _ap) ((void)0) 1177c545bddf806fc1b2e9ce61a9888b49d60471d73junov@chromium.org#endif 1187c545bddf806fc1b2e9ce61a9888b49d60471d73junov@chromium.org 1194868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org 1204868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org#ifdef DEBUG 1214868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org/** 1224868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * Dump a blob in hex to the same place that debug_printf sends its 1234868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org * messages. 1244868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org */ 1254868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.orgvoid debug_print_blob( const char *name, const void *blob, unsigned size ); 1264868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org 1274868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org/* Print a message along with a prettified format string 1284868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org */ 1294868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.orgvoid debug_print_format(const char *msg, unsigned fmt ); 1304868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org#else 1314868e6b221a4a98e40f977851af5fcf09631ea15senorblanco@chromium.org#define debug_print_blob(_name, _blob, _size) ((void)0) 132#define debug_print_format(_msg, _fmt) ((void)0) 133#endif 134 135 136/** 137 * Hard-coded breakpoint. 138 */ 139#ifdef DEBUG 140#define debug_break() os_break() 141#else /* !DEBUG */ 142#define debug_break() ((void)0) 143#endif /* !DEBUG */ 144 145 146long 147debug_get_num_option(const char *name, long dfault); 148 149void _debug_assert_fail(const char *expr, 150 const char *file, 151 unsigned line, 152 const char *function); 153 154 155/** 156 * Assert macro 157 * 158 * Do not expect that the assert call terminates -- errors must be handled 159 * regardless of assert behavior. 160 * 161 * For non debug builds the assert macro will expand to a no-op, so do not 162 * call functions with side effects in the assert expression. 163 */ 164#ifdef DEBUG 165#define debug_assert(expr) ((expr) ? (void)0 : _debug_assert_fail(#expr, __FILE__, __LINE__, __FUNCTION__)) 166#else 167#define debug_assert(expr) do { } while (0 && (expr)) 168#endif 169 170 171/** Override standard assert macro */ 172#ifdef assert 173#undef assert 174#endif 175#define assert(expr) debug_assert(expr) 176 177 178/** 179 * Output the current function name. 180 */ 181#ifdef DEBUG 182#define debug_checkpoint() \ 183 _debug_printf("%s\n", __FUNCTION__) 184#else 185#define debug_checkpoint() \ 186 ((void)0) 187#endif 188 189 190/** 191 * Output the full source code position. 192 */ 193#ifdef DEBUG 194#define debug_checkpoint_full() \ 195 _debug_printf("%s:%u:%s", __FILE__, __LINE__, __FUNCTION__) 196#else 197#define debug_checkpoint_full() \ 198 ((void)0) 199#endif 200 201 202/** 203 * Output a warning message. Muted on release version. 204 */ 205#ifdef DEBUG 206#define debug_warning(__msg) \ 207 _debug_printf("%s:%u:%s: warning: %s\n", __FILE__, __LINE__, __FUNCTION__, __msg) 208#else 209#define debug_warning(__msg) \ 210 ((void)0) 211#endif 212 213 214/** 215 * Output an error message. Not muted on release version. 216 */ 217#ifdef DEBUG 218#define debug_error(__msg) \ 219 _debug_printf("%s:%u:%s: error: %s\n", __FILE__, __LINE__, __FUNCTION__, __msg) 220#else 221#define debug_error(__msg) \ 222 _debug_printf("error: %s\n", __msg) 223#endif 224 225 226/** 227 * Used by debug_dump_enum and debug_dump_flags to describe symbols. 228 */ 229struct debug_named_value 230{ 231 const char *name; 232 unsigned long value; 233}; 234 235 236/** 237 * Some C pre-processor magic to simplify creating named values. 238 * 239 * Example: 240 * @code 241 * static const debug_named_value my_names[] = { 242 * DEBUG_NAMED_VALUE(MY_ENUM_VALUE_X), 243 * DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Y), 244 * DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Z), 245 * DEBUG_NAMED_VALUE_END 246 * }; 247 * 248 * ... 249 * debug_printf("%s = %s\n", 250 * name, 251 * debug_dump_enum(my_names, my_value)); 252 * ... 253 * @endcode 254 */ 255#define DEBUG_NAMED_VALUE(__symbol) {#__symbol, (unsigned long)__symbol} 256#define DEBUG_NAMED_VALUE_END {NULL, 0} 257 258 259/** 260 * Convert a enum value to a string. 261 */ 262const char * 263debug_dump_enum(const struct debug_named_value *names, 264 unsigned long value); 265 266const char * 267debug_dump_enum_noprefix(const struct debug_named_value *names, 268 const char *prefix, 269 unsigned long value); 270 271 272/** 273 * Convert binary flags value to a string. 274 */ 275const char * 276debug_dump_flags(const struct debug_named_value *names, 277 unsigned long value); 278 279 280/** 281 * Get option. 282 * 283 * It is an alias for getenv on Linux. 284 * 285 * On Windows it reads C:\gallium.cfg, which is a text file with CR+LF line 286 * endings with one option per line as 287 * 288 * NAME=value 289 * 290 * This file must be terminated with an extra empty line. 291 */ 292const char * 293debug_get_option(const char *name, const char *dfault); 294 295boolean 296debug_get_bool_option(const char *name, boolean dfault); 297 298long 299debug_get_num_option(const char *name, long dfault); 300 301unsigned long 302debug_get_flags_option(const char *name, 303 const struct debug_named_value *flags, 304 unsigned long dfault); 305 306 307unsigned long 308debug_memory_begin(void); 309 310void 311debug_memory_end(unsigned long beginning); 312 313 314#ifdef DEBUG 315struct pipe_surface; 316struct pipe_transfer; 317void debug_dump_image(const char *prefix, 318 unsigned format, unsigned cpp, 319 unsigned width, unsigned height, 320 unsigned stride, 321 const void *data); 322void debug_dump_surface(const char *prefix, 323 struct pipe_surface *surface); 324void debug_dump_surface_bmp(const char *filename, 325 struct pipe_surface *surface); 326void debug_dump_transfer_bmp(const char *filename, 327 struct pipe_transfer *transfer); 328void debug_dump_float_rgba_bmp(const char *filename, 329 unsigned width, unsigned height, 330 float *rgba, unsigned stride); 331#else 332#define debug_dump_image(prefix, format, cpp, width, height, stride, data) ((void)0) 333#define debug_dump_surface(prefix, surface) ((void)0) 334#define debug_dump_surface_bmp(filename, surface) ((void)0) 335#define debug_dump_transfer_bmp(filename, transfer) ((void)0) 336#define debug_dump_rgba_float_bmp(filename, width, height, rgba, stride) ((void)0) 337#endif 338 339 340#ifdef __cplusplus 341} 342#endif 343 344#endif /* U_DEBUG_H_ */ 345