p_debug.h File Reference

Cross-platform debugging helpers. More...

Include dependency graph for p_debug.h:

Go to the source code of this file.

Data Structures
struct	debug_named_value
	Used by debug_dump_enum and debug_dump_flags to describe symbols. More...
Defines
#define	NDEBUG   1
#define	debug_vprintf(_format, _ap)   ((void)0)
#define	debug_print_blob(_name, _blob, _size)   ((void)0)
#define	debug_print_format(_msg, _fmt)   ((void)0)
#define	debug_break()   ((void)0)
	Hard-coded breakpoint.
#define	debug_assert(expr)   ((void)0)
	Assert macro.
#define	assert(expr)   debug_assert(expr)
	Override standard assert macro.
#define	debug_checkpoint()   ((void)0)
	Output the current function name.
#define	debug_checkpoint_full()   ((void)0)
	Output the full source code position.
#define	debug_warning(__msg)   ((void)0)
	Output a warning message.
#define	debug_error(__msg)   _debug_printf("error: %s\n", __msg)
	Output an error message.
#define	DEBUG_NAMED_VALUE(__symbol)   {#__symbol, (unsigned long)__symbol}
	Some C pre-processor magic to simplify creating named values.
#define	DEBUG_NAMED_VALUE_END   {NULL, 0}
#define	debug_dump_image(prefix, format, cpp, width, height, stride, data)   ((void)0)
#define	debug_dump_surface(prefix, surface)   ((void)0)
#define	debug_dump_surface_bmp(filename, surface)   ((void)0)
Functions
void	_debug_vprintf (const char *format, va_list ap)
static void	_debug_printf (const char *format,...)
static void	debug_printf (const char *format,...)
	Print debug messages.
void	_debug_break (void)
long	debug_get_num_option (const char *name, long dfault)
void	_debug_assert_fail (const char *expr, const char *file, unsigned line, const char *function)
const char *	debug_dump_enum (const struct debug_named_value *names, unsigned long value)
	Convert a enum value to a string.
const char *	debug_dump_flags (const struct debug_named_value *names, unsigned long value)
	Convert binary flags value to a string.
const char *	debug_get_option (const char *name, const char *dfault)
	Get option.
boolean	debug_get_bool_option (const char *name, boolean dfault)
unsigned long	debug_get_flags_option (const char *name, const struct debug_named_value *flags, unsigned long dfault)
void *	debug_malloc (const char *file, unsigned line, const char *function, size_t size)
void	debug_free (const char *file, unsigned line, const char *function, void *ptr)
void *	debug_calloc (const char *file, unsigned line, const char *function, size_t count, size_t size)
void *	debug_realloc (const char *file, unsigned line, const char *function, void *old_ptr, size_t old_size, size_t new_size)
unsigned long	debug_memory_begin (void)
void	debug_memory_end (unsigned long beginning)

---

Detailed Description

Cross-platform debugging helpers.

For now it just has assert and printf replacements, but it might be extended with stack trace reports and more advanced logging in the near future.

Author:

Jose Fonseca <jrfonseca@tungstengraphics.com>

Definition in file p_debug.h.

---

Define Documentation

#define assert

(

expr

)

debug_assert(expr)

Override standard assert macro.

Definition at line 171 of file p_debug.h.

#define debug_assert

(

expr

)

((void)0)

Assert macro.

Do not expect that the assert call terminates -- errors must be handled regardless of assert behavior.

Definition at line 163 of file p_debug.h.

 

#define debug_break

(

)

((void)0)

Hard-coded breakpoint.

Definition at line 141 of file p_debug.h.

 

#define debug_checkpoint

(

)

((void)0)

Output the current function name.

Definition at line 181 of file p_debug.h.

 

#define debug_checkpoint_full

(

)

((void)0)

Output the full source code position.

Definition at line 193 of file p_debug.h.

#define debug_dump_image	(	prefix,
		format,
		cpp,
		width,
		height,
		stride,
		data		)	((void)0)

Definition at line 344 of file p_debug.h.

#define debug_dump_surface	(	prefix,
		surface		)	((void)0)

Definition at line 345 of file p_debug.h.

#define debug_dump_surface_bmp	(	filename,
		surface		)	((void)0)

Definition at line 346 of file p_debug.h.

#define debug_error

(

__msg

)

_debug_printf("error: %s\n", __msg)

Output an error message.

Not muted on release version.

Definition at line 217 of file p_debug.h.

#define DEBUG_NAMED_VALUE

(

__symbol

)

{#__symbol, (unsigned long)__symbol}

Some C pre-processor magic to simplify creating named values.

Example:

 static const debug_named_value my_names[] = {
    DEBUG_NAMED_VALUE(MY_ENUM_VALUE_X),
    DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Y),
    DEBUG_NAMED_VALUE(MY_ENUM_VALUE_Z),
    DEBUG_NAMED_VALUE_END
 };
 
    ...
    debug_printf("%s = %s\n", 
                 name,
                 debug_dump_enum(my_names, my_value));
    ...

Definition at line 251 of file p_debug.h.

#define DEBUG_NAMED_VALUE_END   {NULL, 0}

Definition at line 252 of file p_debug.h.

#define debug_print_blob	(	_name,
		_blob,
		_size		)	((void)0)

Definition at line 121 of file p_debug.h.

#define debug_print_format	(	_msg,
		_fmt		)	((void)0)

Definition at line 122 of file p_debug.h.

#define debug_vprintf	(	_format,
		_ap		)	((void)0)

Definition at line 108 of file p_debug.h.

#define debug_warning

(

__msg

)

((void)0)

Output a warning message.

Muted on release version.

Definition at line 205 of file p_debug.h.

#define NDEBUG   1

Definition at line 58 of file p_debug.h.

---

Function Documentation

void _debug_assert_fail	(	const char *	expr,
		const char *	file,
		unsigned	line,
		const char *	function
	)

Definition at line 337 of file p_debug.c.

References _debug_printf(), debug_break, debug_get_bool_option(), FALSE, and TRUE.

{
   _debug_printf("%s:%u:%s: Assertion `%s' failed.\n", file, line, function, expr);
#if defined(PIPE_OS_WINDOWS) && !defined(PIPE_SUBSYSTEM_WINDOWS_USER)
   if (debug_get_bool_option("GALLIUM_ABORT_ON_ASSERT", FALSE))
#else
   if (debug_get_bool_option("GALLIUM_ABORT_ON_ASSERT", TRUE))
#endif
      debug_break();
   else
      _debug_printf("continuing...\n");
}

void _debug_break

(

void

)

Definition at line 140 of file p_debug.c.

{
#if defined(PIPE_ARCH_X86) && defined(PIPE_CC_GCC)
   __asm("int3");
#elif defined(PIPE_ARCH_X86) && defined(PIPE_CC_MSVC)
   _asm {int 3};
#elif defined(PIPE_SUBSYSTEM_WINDOWS_DISPLAY)
   EngDebugBreak();
#else
   abort();
#endif
}

static void _debug_printf	(	const char *	format,
			...
	)			[static]

Definition at line 73 of file p_debug.h.

References _debug_vprintf().

{
   va_list ap;
   va_start(ap, format);
   _debug_vprintf(format, ap);
   va_end(ap);
}

void _debug_vprintf	(	const char *	format,
		va_list	ap
	)

Definition at line 79 of file p_debug.c.

References util_strchr, and util_vsnprintf.

{
#if defined(PIPE_SUBSYSTEM_WINDOWS_DISPLAY)
   /* EngDebugPrint does not handle float point arguments, so we need to use
    * our own vsnprintf implementation. It is also very slow, so buffer until
    * we find a newline. */
   static char buf[512] = {'\0'};
   size_t len = strlen(buf);
   int ret = util_vsnprintf(buf + len, sizeof(buf) - len, format, ap);
   if(ret > (int)(sizeof(buf) - len - 1) || util_strchr(buf + len, '\n')) {
      _EngDebugPrint("%s", buf);
      buf[0] = '\0';
   }
#elif defined(PIPE_SUBSYSTEM_WINDOWS_USER)
   /* EngDebugPrint does not handle float point arguments, so we need to use
    * our own vsnprintf implementation. It is also very slow, so buffer until
    * we find a newline. */
   static char buf[512 + 1] = {'\0'};
   size_t len = strlen(buf);
   int ret = util_vsnprintf(buf + len, sizeof(buf) - len, format, ap);
   if(ret > (int)(sizeof(buf) - len - 1) || util_strchr(buf + len, '\n')) {
      OutputDebugStringA(buf);
      buf[0] = '\0';
   }

   
   if(GetConsoleWindow() && !IsDebuggerPresent()) {
      fflush(stdout);
      vfprintf(stderr, format, ap);
      fflush(stderr);
   }
   

#elif defined(PIPE_SUBSYSTEM_WINDOWS_CE) || defined(PIPE_SUBSYSTEM_WINDOWS_MINIPORT) 
   /* TODO */
#else /* !PIPE_SUBSYSTEM_WINDOWS */
#ifdef DEBUG
   vfprintf(stderr, format, ap);
#endif
#endif
}

void* debug_calloc	(	const char *	file,
		unsigned	line,
		const char *	function,
		size_t	count,
		size_t	size
	)

Definition at line 184 of file p_debug_mem.c.

References debug_malloc().

{
   void *ptr = debug_malloc( file, line, function, count * size );
   if( ptr )
      memset( ptr, 0, count * size );
   return ptr;
}

const char* debug_dump_enum	(	const struct debug_named_value *	names,
		unsigned long	value
	)

Convert a enum value to a string.

Definition at line 355 of file p_debug.c.

References debug_named_value::name, util_snprintf, and debug_named_value::value.

{
   static char rest[64];
   
   while(names->name) {
      if(names->value == value)
         return names->name;
      ++names;
   }

   util_snprintf(rest, sizeof(rest), "0x%08lx", value);
   return rest;
}

const char* debug_dump_flags	(	const struct debug_named_value *	names,
		unsigned long	value
	)

Convert binary flags value to a string.

Definition at line 372 of file p_debug.c.

References debug_named_value::name, util_snprintf, util_strncat, and debug_named_value::value.

{
   static char output[4096];
   static char rest[256];
   int first = 1;

   output[0] = '\0';

   while(names->name) {
      if((names->value & value) == names->value) {
         if (!first)
            util_strncat(output, "|", sizeof(output));
         else
            first = 0;
         util_strncat(output, names->name, sizeof(output));
         value &= ~names->value;
      }
      ++names;
   }
   
   if (value) {
      if (!first)
         util_strncat(output, "|", sizeof(output));
      else
         first = 0;
      
      util_snprintf(rest, sizeof(rest), "0x%08lx", value);
      util_strncat(output, rest, sizeof(output));
   }
   
   if(first)
      return "0";
   
   return output;
}

void debug_free	(	const char *	file,
		unsigned	line,
		const char *	function,
		void *	ptr
	)

Definition at line 150 of file p_debug_mem.c.

References debug_assert, DEBUG_MEMORY_MAGIC, debug_printf(), debug_memory_header::file, footer_from_header(), debug_memory_header::function, debug_memory_header::head, header_from_data(), debug_memory_header::line, LIST_DEL, debug_memory_footer::magic, debug_memory_header::magic, and real_free.

{
   struct debug_memory_header *hdr;
   struct debug_memory_footer *ftr;
   
   if(!ptr)
      return;
   
   hdr = header_from_data(ptr);
   if(hdr->magic != DEBUG_MEMORY_MAGIC) {
      debug_printf("%s:%u:%s: freeing bad or corrupted memory %p\n",
                   file, line, function,
                   ptr);
      debug_assert(0);
      return;
   }

   ftr = footer_from_header(hdr);
   if(ftr->magic != DEBUG_MEMORY_MAGIC) {
      debug_printf("%s:%u:%s: buffer overflow %p\n",
                   hdr->file, hdr->line, hdr->function,
                   ptr);
      debug_assert(0);
   }

   LIST_DEL(&hdr->head);
   hdr->magic = 0;
   ftr->magic = 0;
   
   real_free(hdr);
}

boolean debug_get_bool_option	(	const char *	name,
		boolean	dfault
	)

Definition at line 251 of file p_debug.c.

References _debug_get_option(), debug_printf(), FALSE, TRUE, and util_strcmp.

{
   const char *str = _debug_get_option(name);
   boolean result;
   
   if(str == NULL)
      result = dfault;
   else if(!util_strcmp(str, "n"))
      result = FALSE;
   else if(!util_strcmp(str, "no"))
      result = FALSE;
   else if(!util_strcmp(str, "0"))
      result = FALSE;
   else if(!util_strcmp(str, "f"))
      result = FALSE;
   else if(!util_strcmp(str, "false"))
      result = FALSE;
   else
      result = TRUE;

   debug_printf("%s: %s = %s\n", __FUNCTION__, name, result ? "TRUE" : "FALSE");
   
   return result;
}

unsigned long debug_get_flags_option	(	const char *	name,
		const struct debug_named_value *	flags,
		unsigned long	dfault
	)

Definition at line 312 of file p_debug.c.

References _debug_get_option(), debug_printf(), debug_named_value::name, util_strcmp, util_strstr, and debug_named_value::value.

{
   unsigned long result;
   const char *str;
   
   str = _debug_get_option(name);
   if(!str)
      result = dfault;
   else {
      result = 0;
      while( flags->name ) {
         if (!util_strcmp(str, "all") || util_strstr(str, flags->name ))
            result |= flags->value;
         ++flags;
      }
   }

   debug_printf("%s: %s = 0x%lx\n", __FUNCTION__, name, result);

   return result;
}

long debug_get_num_option	(	const char *	name,
		long	dfault
	)

Definition at line 278 of file p_debug.c.

References _debug_get_option(), and debug_printf().

{
   long result;
   const char *str;
   
   str = _debug_get_option(name);
   if(!str)
      result = dfault;
   else {
      long sign;
      char c;
      c = *str++;
      if(c == '-') {
         sign = -1;
         c = *str++;
      } 
      else {
         sign = 1;
      }
      result = 0;
      while('0' <= c && c <= '9') {
         result = result*10 + (c - '0');
         c = *str++;
      }
      result *= sign;
   }
   
   debug_printf("%s: %s = %li\n", __FUNCTION__, name, result);

   return result;
}

const char* debug_get_option	(	const char *	name,
		const char *	dfault
	)

Get option.

It is an alias for getenv on Linux.

On Windows it reads C:.cfg, which is a text file with CR+LF line endings with one option per line as

NAME=value

This file must be terminated with an extra empty line.

Definition at line 237 of file p_debug.c.

References _debug_get_option(), and debug_printf().

{
   const char *result;

   result = _debug_get_option(name);
   if(!result)
      result = dfault;
      
   debug_printf("%s: %s = %s\n", __FUNCTION__, name, result ? result : "(null)");
   
   return result;
}

void* debug_malloc	(	const char *	file,
		unsigned	line,
		const char *	function,
		size_t	size
	)

Definition at line 118 of file p_debug_mem.c.

References assert, data_from_header(), DEBUG_MEMORY_MAGIC, debug_printf(), debug_memory_header::file, footer_from_header(), debug_memory_header::function, debug_memory_header::head, last_no, debug_memory_header::line, LIST_ADDTAIL, debug_memory_footer::magic, debug_memory_header::magic, debug_memory_header::no, real_malloc, and debug_memory_header::size.

{
   struct debug_memory_header *hdr;
   struct debug_memory_footer *ftr;
   
   assert(size);
   
   hdr = real_malloc(sizeof(*hdr) + size + sizeof(*ftr));
   if(!hdr) {
      debug_printf("%s:%u:%s: out of memory when trying to allocate %lu bytes\n",
                   file, line, function,
                   (long unsigned)size);
      return NULL;
   }
 
   hdr->no = last_no++;
   hdr->file = file;
   hdr->line = line;
   hdr->function = function;
   hdr->size = size;
   hdr->magic = DEBUG_MEMORY_MAGIC;

   ftr = footer_from_header(hdr);
   ftr->magic = DEBUG_MEMORY_MAGIC;
   
   LIST_ADDTAIL(&hdr->head, &list);
   
   return data_from_header(hdr);
}

unsigned long debug_memory_begin

(

void

)

Definition at line 259 of file p_debug_mem.c.

References last_no.

{
   return last_no;
}

void debug_memory_end

(

unsigned long

beginning

)

Definition at line 265 of file p_debug_mem.c.

References data_from_header(), debug_assert, DEBUG_MEMORY_MAGIC, debug_printf(), debug_memory_header::file, footer_from_header(), debug_memory_header::function, last_no, debug_memory_header::line, LIST_ENTRY, debug_memory_footer::magic, debug_memory_header::magic, debug_memory_header::no, list_head::prev, and debug_memory_header::size.

{
   size_t total_size = 0;
   struct list_head *entry;

   if(start_no == last_no)
      return;

   entry = list.prev;
   for (; entry != &list; entry = entry->prev) {
      struct debug_memory_header *hdr;
      void *ptr;
      struct debug_memory_footer *ftr;

      hdr = LIST_ENTRY(struct debug_memory_header, entry, head);
      ptr = data_from_header(hdr);
      ftr = footer_from_header(hdr);

      if(hdr->magic != DEBUG_MEMORY_MAGIC) {
         debug_printf("%s:%u:%s: bad or corrupted memory %p\n",
                      hdr->file, hdr->line, hdr->function,
                      ptr);
         debug_assert(0);
      }

      if((start_no <= hdr->no && hdr->no < last_no) ||
         (last_no < start_no && (hdr->no < last_no || start_no <= hdr->no))) {
         debug_printf("%s:%u:%s: %u bytes at %p not freed\n",
                      hdr->file, hdr->line, hdr->function,
                      hdr->size, ptr);
         total_size += hdr->size;
      }

      if(ftr->magic != DEBUG_MEMORY_MAGIC) {
         debug_printf("%s:%u:%s: buffer overflow %p\n",
                      hdr->file, hdr->line, hdr->function,
                      ptr);
         debug_assert(0);
      }
   }

   if(total_size) {
      debug_printf("Total of %u KB of system memory apparently leaked\n",
                   (total_size + 1023)/1024);
   }
   else {
      debug_printf("No memory leaks detected.\n");
   }
}

static void debug_printf	(	const char *	format,
			...
	)			[static]

Print debug messages.

The actual channel used to output debug message is platform specific. To avoid misformating or truncation, follow these rules of thumb:

• output whole lines
• avoid outputing large strings (512 bytes is the current maximum length that is guaranteed to be printed in all platforms)

Definition at line 92 of file p_debug.h.

References _debug_vprintf().

{
#ifdef DEBUG
   va_list ap;
   va_start(ap, format);
   _debug_vprintf(format, ap);
   va_end(ap);
#else
   (void) format; /* silence warning */
#endif
}

void* debug_realloc	(	const char *	file,
		unsigned	line,
		const char *	function,
		void *	old_ptr,
		size_t	old_size,
		size_t	new_size
	)

Definition at line 194 of file p_debug_mem.c.

References data_from_header(), debug_assert, debug_free(), debug_malloc(), DEBUG_MEMORY_MAGIC, debug_printf(), debug_memory_header::file, footer_from_header(), debug_memory_header::function, debug_memory_header::head, header_from_data(), debug_memory_header::line, LIST_REPLACE, debug_memory_footer::magic, debug_memory_header::magic, debug_memory_header::no, real_free, real_malloc, and debug_memory_header::size.

{
   struct debug_memory_header *old_hdr, *new_hdr;
   struct debug_memory_footer *old_ftr, *new_ftr;
   void *new_ptr;
   
   if(!old_ptr)
      return debug_malloc( file, line, function, new_size );
   
   if(!new_size) {
      debug_free( file, line, function, old_ptr );
      return NULL;
   }
   
   old_hdr = header_from_data(old_ptr);
   if(old_hdr->magic != DEBUG_MEMORY_MAGIC) {
      debug_printf("%s:%u:%s: reallocating bad or corrupted memory %p\n",
                   file, line, function,
                   old_ptr);
      debug_assert(0);
      return NULL;
   }
   
   old_ftr = footer_from_header(old_hdr);
   if(old_ftr->magic != DEBUG_MEMORY_MAGIC) {
      debug_printf("%s:%u:%s: buffer overflow %p\n",
                   old_hdr->file, old_hdr->line, old_hdr->function,
                   old_ptr);
      debug_assert(0);
   }

   /* alloc new */
   new_hdr = real_malloc(sizeof(*new_hdr) + new_size + sizeof(*new_ftr));
   if(!new_hdr) {
      debug_printf("%s:%u:%s: out of memory when trying to allocate %lu bytes\n",
                   file, line, function,
                   (long unsigned)new_size);
      return NULL;
   }
   new_hdr->no = old_hdr->no;
   new_hdr->file = old_hdr->file;
   new_hdr->line = old_hdr->line;
   new_hdr->function = old_hdr->function;
   new_hdr->size = new_size;
   new_hdr->magic = DEBUG_MEMORY_MAGIC;
   
   new_ftr = footer_from_header(new_hdr);
   new_ftr->magic = DEBUG_MEMORY_MAGIC;
   
   LIST_REPLACE(&old_hdr->head, &new_hdr->head);

   /* copy data */
   new_ptr = data_from_header(new_hdr);
   memcpy( new_ptr, old_ptr, old_size < new_size ? old_size : new_size );

   /* free old */
   old_hdr->magic = 0;
   old_ftr->magic = 0;
   real_free(old_hdr);

   return new_ptr;
}

---