Debug.h

00001 /* mbed Debug library used by all my developed program
00002  * Copyright (c) 2010-2012 ygarcia, MIT License
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy of this software 
00005  * and associated documentation files (the "Software"), to deal in the Software without restriction, 
00006  * including without limitation the rights to use, copy, modify, merge, publish, distribute, 
00007  * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is 
00008  * furnished to do so, subject to the following conditions:
00009  *
00010  * The above copyright notice and this permission notice shall be included in all copies or 
00011  * substantial portions of the Software.
00012  *
00013  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING 
00014  * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
00015  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, 
00016  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
00017  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00018  */
00019 #if !defined(__DEBUG_H__)
00020 #define __DEBUG_H__
00021 
00022 #include "mbed.h"
00023 
00024 /** The steps below describe how to use this library:
00025  * 1. Import this library to your project 'As file', because you will need to modify this file as described in step 2
00026  * 2. Edit this library
00027  * 3. Remove comment from line 66 (search for '//#define __DEBUG' in this file) to get the DEBUG macro defimed properly. By default, __DEBUG flahg is undef
00028  * 4. Rebuild this library and use the debug macro as decribe in sample code
00029  *
00030  * IMPORTANT: If you modify this libray, please keep this comment up to date for future users
00031  *
00032  * Please refer to handbook (http://mbed.org/handbook/Debugging) for mbed Debugging support
00033  *
00034  * @code
00035  * #include "Debug.h"                          // This header alway includes mbed.h file
00036  * 
00037  * DigitalOut myled(LED1);
00038  * 
00039  * int main() {
00040  *     DEBUG_ENTER("main")                     // Log the entry of the C function 'main'
00041  *
00042  *     std::string str("This is a sample for heaxdecimal dump using DebugLibrary");
00043  *     DEBUG(">>> Example:");
00044  *     HEXADUMP((unsigned char *)str.c_str(), str.length());
00045  *     DEBUG("===");
00046  *     HEXADUMP_OFFSET((unsigned char *)str.c_str(), str.length() - 19, 19);
00047  *     DEBUG("<<<");
00048  *
00049  *     int counter = 0;
00050  *     while(1) {
00051  *         DEBUG("In loop [%d]", counter++)    // A sample message
00052  *         myled = 1;
00053  *         wait(0.2);
00054  *         myled = 0;
00055  *         wait(0.2);
00056  *         DEBUG_BREAK()                       // Wait for any key pressed to continue
00057  *     } // End of 'while' statement
00058  *     DEBUG_LEAVE("main, never reached")      // Log the end of the C function 'main'
00059  * }
00060  * @endcode
00061  */
00062 //#undef __DEBUG //<! Undefined debug flah, default value
00063 #define __DEBUG //<! Uncomment this line to activate debug macros
00064 
00065 // Undefined DEBUG symbols to be sure to use mine
00066 #undef DEBUG_ENTER
00067 #undef DEBUG_LEAVE
00068 #undef DEBUG
00069 #undef HEXADUMP
00070 #undef HEXADUMP_OFFSET
00071 #undef DEBUG_ERROR
00072 #undef DEBUG_WARNING
00073 #undef DEBUG_BREAK
00074 #undef DEBUG_FATAL
00075 
00076 #ifdef __DEBUG
00077 
00078 /** This class implements debug functionalities based on USB console interface. V0.0.0.8
00079  *
00080  * Note that this class is based on Helper pattern
00081  */
00082 class DebugHelper
00083 {
00084     /** Convert the specified digit into hexadecimal number (0x30..0x39 (0..9), 0x47..x4c (A..F))
00085      *
00086      * @param p_digit The digit to convert
00087      * @return An hexadecimal digit (0..9-A..F)
00088      */
00089     static inline unsigned char ToHexDigit(unsigned char p_digit) { return ((p_digit < 10) ? (p_digit + 0x30) : (p_digit + 0x37)); };
00090     /** Convert the specified hexadecimal digit into a character if it is printable, or replace by a '.' otherwise
00091      *
00092      * @param p_digit The hexadecimal digit to convert
00093      * @return A character is it's printable, '.' otherwise
00094      */
00095     static inline char ToCharDigit(unsigned char p_digit) { return (((p_digit < 0x20) || (p_digit > 0x80)) ? '.' : (char)p_digit); };
00096 public:
00097     /** Standard log method
00098      * @param p_format Format string compliant with C 'printf' format string
00099      */
00100     static void Debug(const char* p_format, ...);
00101     /** Log an hexadecimal buffer
00102      *
00103      * Note that parameters 'p_offset' and 'p_length' are not supported yet
00104      *
00105      * @param p_buffer The buffer to dump
00106      * @param p_count Number of bytes to dump
00107      * @param p_offset Offset to start the dump. Default: 0
00108      */
00109     static void HexaDump(unsigned char* p_buffer, int p_count, int p_offset = 0);
00110     /** Break point method based on getchar() C function
00111      */
00112     static void BreakPoint(const char* p_file, int p_line);
00113 }; // End of class DebugHelper
00114 
00115 /** Used to log function/method entry (>> )
00116  *
00117  * Note that \ for multiline macro is not supported yet
00118  */
00119 #define DEBUG_ENTER(...) do { DebugHelper::Debug(">> "); DebugHelper::Debug(__VA_ARGS__); DebugHelper::Debug("\r\n"); } while(false);
00120 /** Used to log function end of function/method (<< )
00121  *
00122  * Note that \ for multiline macro is not supported yet
00123  */
00124 #define DEBUG_LEAVE(...) do { DebugHelper::Debug("<< "); DebugHelper::Debug(__VA_ARGS__); DebugHelper::Debug("\r\n"); } while(false);
00125 /** Used to log a standard message
00126  *
00127  * Note that \ for multiline macro is not supported yet
00128  */
00129 #define DEBUG(...) do { DebugHelper::Debug(__VA_ARGS__); DebugHelper::Debug("\r\n"); } while(false);
00130 /** Used to dump an hexadecimal buffer
00131  *
00132  * Note that \ for multiline macro is not supported yet
00133  */
00134 #define HEXADUMP(p_buffer, p_count) DebugHelper::HexaDump(p_buffer, p_count);
00135 /** Used to dump an hexadecimal buffer with an offset
00136  *
00137  * Note that \ for multiline macro is not supported yet
00138  */
00139 #define HEXADUMP_OFFSET(p_buffer, p_count, p_offset) DebugHelper::HexaDump(p_buffer, p_count, p_offset);
00140 /** Used to log an error message (?? )
00141  *
00142  * Note that \ for multiline macro is not supported yet
00143  */
00144 #define DEBUG_ERROR(...) do { DebugHelper::Debug("?? "); DebugHelper::Debug(__VA_ARGS__); DebugHelper::Debug("\r\n"); } while(false);
00145 /** Used to log a warning message (!! )
00146  *
00147  * Note that \ for multiline macro is not supported yet
00148  */
00149 #define DEBUG_WARNING(...) do { DebugHelper::Debug("!! "); DebugHelper::Debug(__VA_ARGS__); DebugHelper::Debug("\r\n"); } while(false);
00150 
00151 /** Break point macro
00152  */
00153 #define DEBUG_BREAK() DebugHelper::BreakPoint(__FILE__, __LINE__);
00154 
00155 /** Used to stop program on fatal error
00156  */
00157 #define DEBUG_FATAL(cause) error(cause);
00158 
00159 #else // __DEBUG
00160 
00161 /** Undefine DEBUG macro, used when __DEBUG is undefined
00162  */
00163 #define DEBUG_ENTER(...)
00164 /** Undefine DEBUG macro, used when __DEBUG is undefined
00165  */
00166 #define DEBUG_LEAVE(...)
00167 /** Undefine DEBUG macro, used when __DEBUG is undefined
00168  */
00169 #define DEBUG(...)
00170 /** Undefine DEBUG macro, used when __DEBUG is undefined
00171  *
00172  * Note that \ for multiline macro is not supported yet
00173  */
00174 #define HEXADUMP(p_buffer, p_count)
00175 /** Undefine DEBUG macro, used when __DEBUG is undefined
00176  *
00177  * Note that \ for multiline macro is not supported yet
00178  */
00179 #define HEXADUMP_OFFSET(p_buffer, p_count, p_offset)
00180 /** Undefine DEBUG_ERROR macro, used when __DEBUG is undefined
00181  */
00182 #define DEBUG_ERROR(...)
00183 /** Undefine DEBUG_WARNING macro, used when __DEBUG is undefined
00184  */
00185 #define DEBUG_WARNING(...)
00186 
00187 /** Undefine DEBUG_BREAK macro, used when __DEBUG is undefined
00188  */
00189 #define DEBUG_BREAK()
00190 
00191 /** Undefine DEBUG_FATAL macro, used when __DEBUG is undefined
00192  */
00193 #define DEBUG_FATAL(cause)
00194 
00195 #endif // __DEBUG
00196   
00197 #endif // __DEBUG_H__