debug.h

   1 /*!
   2  * \file
   3  * <!--
   4  * Copyright 2003, 2004 Develer S.r.l. (http://www.develer.com/)
   5  * This file is part of DevLib - See devlib/README for information.
   6  * -->
   7  *
   8  * \brief Simple debug facilities for hosted and embedded C/C++ applications.
   9  *
  10  * Debug output goes to stderr in hosted applications.
  11  * Freestanding (AKA embedded) applications use \c drv/kdebug.c to output
  12  * diagnostic messages to a serial terminal or a JTAG debugger.
  13  *
  14  * \version $Id$
  15  * \author Bernardo Innocenti <bernie@develer.com>
  16  */
  17
  18 /*#*
  19  *#* $Log$
  20  *#* Revision 1.6  2004/12/08 08:52:00  bernie
  21  *#* Save some more RAM on AVR.
  22  *#*
  23  *#* Revision 1.5  2004/12/08 08:04:13  bernie
  24  *#* Doxygen fixes.
  25  *#*
  26  *#* Revision 1.4  2004/12/08 07:29:27  bernie
  27  *#* Fix Doxygen tags.
  28  *#*
  29  *#* Revision 1.3  2004/09/20 03:31:27  bernie
  30  *#* Sanitize for C++.
  31  *#*
  32  *#* Revision 1.2  2004/09/14 21:01:46  bernie
  33  *#* Mark assertions as LIKELY().
  34  *#*
  35  *#* Revision 1.1  2004/09/14 20:19:47  bernie
  36  *#* Unified debug macros.
  37  *#*
  38  *#* Revision 1.3  2004/09/06 12:11:29  bernie
  39  *#* Merge debug.h with DevLib.
  40  *#*
  41  *#* Revision 1.2  2004/08/13 03:22:07  bernie
  42  *#* Resurrect some debug macros from old projects.
  43  *#*
  44  *#* Revision 1.1  2004/08/12 06:56:35  bernie
  45  *#* Move debug.h from device/ to util/.
  46  *#*
  47  *#* Revision 1.1  2004/08/12 06:52:26  bernie
  48  *#* Factor out a few simple debug macros.
  49  *#*
  50  *#*/
  51 #ifndef DEVLIB_DEBUG_H
  52 #define DEVLIB_DEBUG_H
  53
  54 /*
  55  * Try to guess whether we're running in a hosted or embedded environment.
  56  */
  57 #ifndef OS_HOSTED
  58         #if defined(__unix__) || defined(_WIN32)
  59                 #define OS_HOSTED  1
  60         #else
  61                 #define OS_HOSTED  0
  62         #endif
  63 #endif /* !OS_HOSTED */
  64
  65 #if OS_HOSTED
  66         /*
  67          * For now, avoid dependency on compiler.h
  68          */
  69         #ifndef FORMAT
  70         #define FORMAT(x,y,z) /* nothing */
  71         #endif
  72         #ifndef INLINE
  73         #define INLINE static inline
  74         #endif
  75         #ifndef UNUSED
  76         #define UNUSED(type,name) type
  77         #endif
  78 #else /* !OS_HOSTED */
  79         #include <config.h>
  80         #include <compiler.h>
  81 #endif /* !OS_HOSTED */
  82
  83 /*
  84  * This preprocessor symbol is defined only in debug builds.
  85  *
  86  * The build infrastructure must arrange for _DEBUG to
  87  * be prepredefined for all source files being compiled.
  88  *
  89  * This is compatible with the Microsoft convention for
  90  * the default Debug and Release targets.
  91  */
  92 #ifdef _DEBUG
  93
  94         // STLport specific: enable extra checks
  95         #define __STL_DEBUG 1
  96
  97         // MSVC specific: Enable memory allocation debug
  98         #if defined(_MSC_VER)
  99                 #include <crtdbg.h>
 100         #endif
 101
 102         /*
 103          * On UNIX systems the extabilished practice is to define
 104          * NDEBUG for release builds and nothing for debug builds.
 105          */
 106         #ifdef NDEBUG
 107         #undef NDEBUG
 108         #endif
 109
 110         /*!
 111          * This macro duplicates the old MSVC trick of redefining
 112          * THIS_FILE locally to avoid the overhead of many duplicate
 113          * strings in ASSERT().
 114          */
 115         #ifndef THIS_FILE
 116                 #define THIS_FILE  __FILE__
 117         #endif
 118
 119         /*!
 120          * This macro can be used to conditionally exclude one or more
 121          * statements conditioned on \c _DEBUG, avoiding the clutter
 122          * of #ifdef/#endif pairs.
 123          *
 124          * \code
 125          *     struct FooBar
 126          *     {
 127          *         int foo;
 128          *         bool bar;
 129          *         DB(int ref_count;) // Track number of users
 130          *
 131          *         void release()
 132          *         {
 133          *             DB(--ref_count;)
 134          *         }
 135          *     };
 136          * \endcode
 137          */
 138         #define DB(x) x
 139
 140         #if OS_HOSTED
 141                 #include <stdio.h>
 142                 #include <stdarg.h>
 143                 INLINE void kdbg_init(void) { /* nop */ }
 144                 INLINE void kputchar(char c)
 145                 {
 146                         putc(c, stderr);
 147                 }
 148                 INLINE void kputs(const char *str)
 149                 {
 150                         fputs(str, stderr);
 151                 }
 152                 INLINE void kprintf(const char * fmt, ...) FORMAT(__printf__, 1, 2)
 153                 {
 154                         va_list ap;
 155                         va_start(ap, fmt);
 156                         vfprintf(stderr, fmt, ap);
 157                         va_end(ap);
 158                 }
 159                 void kdump(const void *buf, size_t len); /* UNIMPLEMENTED */
 160
 161                 #ifndef ASSERT
 162                         #include <assert.h>
 163                         #define ASSERT(x) assert(x)
 164                 #endif /* ASSERT */
 165
 166                 /*!
 167                  * Check that the given pointer is not NULL or pointing to raw memory.
 168                  *
 169                  * The assumption here is that valid pointers never point to low
 170                  * memory regions.  This helps catching pointers taken from
 171                  * struct/class memebers when the struct pointer was NULL.
 172                  */
 173                 #define ASSERT_VALID_PTR(p)  ASSERT((unsigned long)(p) > 0x200)
 174
 175                 #define ASSERT_VALID_PTR_OR_NULL(p)  ASSERT((((p) == NULL) || ((unsigned long)(p) >= 0x200)))
 176         #else /* !OS_HOSTED */
 177
 178                 /* These are implemented in drv/kdebug.c */
 179                 void kdbg_init(void);
 180                 void kputchar(char c);
 181                 void kdump(const void *buf, size_t len);
 182                 void __init_wall(long *wall, int size);
 183
 184                 #ifdef __AVR__
 185                         #include <avr/pgmspace.h>
 186                         void kputs_P(const char *PROGMEM str);
 187                         void kprintf_P(const char *PROGMEM fmt, ...) FORMAT(__printf__, 1, 2);
 188                         int __assert_P(const char *PROGMEM cond, const char *PROGMEM file, int line);
 189                         int __invalid_ptr_P(void *p, const char *PROGMEM name, const char *PROGMEM file, int line);
 190                         int __check_wall_P(long *wall, int size, const char * PGM_ATTR name, const char * PGM_ATTR file, int line);
 191                         #define kputs(str)  kputs_P(PSTR(str))
 192                         #define kprintf(fmt, ...)  kprintf_P(PSTR(fmt) ,## __VA_ARGS__)
 193                         #define __assert(cond, file, line)  __assert_P(PSTR(cond), PSTR(file), (line))
 194                         #define __invalid_ptr(p, name, file, line)  __invalid_ptr_P((p), PSTR(name), PSTR(file), (line))
 195                         #define __check_wall(wall, size, name, file, line)  __check_wall_P(wall, size, PSTR(name), PSTR(file), (line))
 196                 #else /* !__AVR__ */
 197                         void kputs(const char *str);
 198                         void kprintf(const char * fmt, ...) FORMAT(__printf__, 1, 2);
 199                         int __assert(const char *cond, const char *file, int line);
 200                         int __invalid_ptr(void *p, const char *name, const char *file, int line);
 201                         int __check_wall(long *wall, int size, const char *name, const char *file, int line);
 202                 #endif /* !__AVR__ */
 203
 204                 #ifndef CONFIG_KDEBUG_ASSERT_NO_TEXT
 205                         #define ASSERT(x)         ((void)(LIKELY(x) ? 0 : __assert(#x, THIS_FILE, __LINE__)))
 206                         #define ASSERT2(x, help)  ((void)(LIKELY(x) ? 0 : __assert(help " (" #x ")", THIS_FILE, __LINE__)))
 207                 #else
 208                         #define ASSERT(x)         ((void)(LIKELY(x) ? 0 : __assert("", THIS_FILE, __LINE__)))
 209                         #define ASSERT2(x, help)  ((void)ASSERT(x))
 210                 #endif
 211
 212                 #define ASSERT_VALID_PTR(p)         ((void)(LIKELY((p) >= 0x200) ? 0 : __invalid_ptr(p, #p, THIS_FILE, __LINE__)))
 213                 #define ASSERT_VALID_PTR_OR_NULL(p) ((void)(LIKELY((p == NULL) || ((p) >= 0x200)) ? 0 : __invalid_ptr((p), #p, THIS_FILE, __LINE__)))
 214                 #define TRACE                       kprintf("%s()\n", __FUNCTION__)
 215                 #define TRACEMSG(msg,...)           kprintf("%s(): " msg "\n", __FUNCTION__, ## __VA_ARGS__)
 216
 217         #endif /* !OS_HOSTED */
 218
 219         /*!
 220          * \name Walls to detect data corruption
 221          * \{
 222          */
 223         #define WALL_SIZE                    8
 224         #define WALL_VALUE                   (long)0xABADCAFEL
 225         #define DECLARE_WALL(name,size)      long name[(size) / sizeof(long)];
 226         #define FWD_DECLARE_WALL(name,size)  extern long name[(size) / sizeof(long)];
 227         #define INIT_WALL(name)              __init_wall((name), countof(name))
 228         #define CHECK_WALL(name)             __check_wall((name), countof(name), #name, THIS_FILE, __LINE__)
 229         /*\}*/
 230
 231         /*!
 232          * Check that the given pointer actually points to an object
 233          * of the specified type.
 234          */
 235         #define ASSERT_VALID_OBJ(_t, _o) do { \
 236                 ASSERT_VALID_PTR((_o)); \
 237                 ASSERT(dynamic_cast<_t>((_o)) != NULL); \
 238         }
 239
 240         /*!
 241          * \name Debug object creation and destruction.
 242          *
 243          * These macros help track some kinds of leaks in C++ programs.
 244          * Usage is as follows:
 245          *
 246          * \code
 247          *   class Foo
 248          *   {
 249          *       DECLARE_INSTANCE_TRACKING(Foo)
 250          *
 251          *       Foo()
 252          *       {
 253          *           NEW_INSTANCE(Foo);
 254          *           // ...
 255          *       }
 256          *
 257          *       ~Foo()
 258          *       {
 259          *           DELETE_INSTANCE(Foo);
 260          *           // ...
 261          *       }
 262          *   };
 263          *
 264          *   // Put this in the implementation file of the class
 265          *   IMPLEMENT_INSTANCE_TRACKING(Foo)
 266          *
 267          *   // Client code
 268          *   int main(void)
 269          *   {
 270          *        Foo *foo = new Foo;
 271          *        cout << GET_INSTANCE_COUNT(Foo) << endl; // prints "1"
 272          *        delete foo;
 273          *        ASSERT_ZERO_INSTANCES(Foo); // OK
 274          *   }
 275          * \endcode
 276          * \{
 277          */
 278         #define NEW_INSTANCE(CLASS)                do { ++CLASS::__instances } while (0)
 279         #define DELETE_INSTANCE(CLASS)             do { --CLASS::__instances } while (0)
 280         #define ASSERT_ZERO_INSTANCES(CLASS)       ASSERT(CLASS::__instances == 0)
 281         #define GET_INSTANCE_COUNT(CLASS)          (CLASS::__instances)
 282         #define DECLARE_INSTANCE_TRACKING(CLASS)   static int __instances
 283         #define IMPLEMENT_INSTANCE_TRACKING(CLASS) int CLASS::__instances = 0
 284         /*\}*/
 285
 286 #else /* !_DEBUG */
 287
 288         /*
 289          * On UNIX systems the extabilished practice is to define
 290          * NDEBUG for release builds and nothing for debug builds.
 291          */
 292         #ifndef NDEBUG
 293         #define NDEBUG 1
 294         #endif
 295
 296         #define DB(x)  /* nothing */
 297         #ifndef ASSERT
 298                 #define ASSERT(x)  do {} while (0)
 299         #endif /* ASSERT */
 300         #define ASSERT2(x, help)             do {} while (0)
 301         #define ASSERT_VALID_PTR(p)          do {} while (0)
 302         #define ASSERT_VALID_PTR_OR_NULL(p)  do {} while (0)
 303         #define ASSERT_VALID_OBJ(_t, _o)     do {} while (0)
 304         #define TRACE                        do {} while (0)
 305         #define TRACEMSG(x,...)              do {} while (0)
 306
 307         #define DECLARE_WALL(name, size)     /* nothing */
 308         #define FWD_DECLARE_WALL(name, size) /* nothing */
 309         #define INIT_WALL(name)              do {} while (0)
 310         #define CHECK_WALL(name)             do {} while (0)
 311
 312         #define NEW_INSTANCE(CLASS)                do {} while (0)
 313         #define DELETE_INSTANCE(CLASS)             do {} while (0)
 314         #define ASSERT_ZERO_INSTANCES(CLASS)       do {} while (0)
 315         #define GET_INSTANCE_COUNT(CLASS)          ERROR_ONLY_FOR_DEBUG
 316         #define DECLARE_INSTANCE_TRACKING(CLASS)
 317         #define IMPLEMENT_INSTANCE_TRACKING(CLASS)
 318
 319         INLINE void kdbg_init(void) { /* nop */ }
 320         INLINE void kputchar(UNUSED(char, c)) { /* nop */ }
 321         INLINE void kputs(UNUSED(const char*, str)) { /* nop */ }
 322         #ifdef __cplusplus
 323                 /* G++ can't inline functions with variable arguments... */
 324                 #define kprintf(fmt,...) do { (void)(fmt); } while(0)
 325         #else
 326                 /* ...but GCC can. */
 327                 INLINE void kprintf(UNUSED(const char*, fmt), ...) { /* nop */ }
 328         #endif
 329
 330 #endif /* _DEBUG */
 331
 332 #endif /* DEVLIB_DEBUG_H */