debug.h

00001 /*******************************************************************************
00002 ################################################################################
00003 #                             (C) STMicroelectronics 2014
00004 #
00005 # This program is free software; you can redistribute it and/or modify it under
00006 # the terms of the GNU General Public License version 2 and only version 2 as
00007 # published by the Free Software Foundation.
00008 #
00009 # This program is distributed in the hope that it will be useful, but WITHOUT
00010 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00011 # FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
00012 # details.
00013 #
00014 # You should have received a copy of the GNU General Public License along with
00015 # this program; if not, write to the Free Software Foundation, Inc.,
00016 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
00017 #
00018 #------------------------------------------------------------------------------
00019 #                             Imaging Division
00020 ################################################################################
00021 ********************************************************************************/
00022 
00023 /*!
00024  *\file debug.h
00025  *\brief All debug related features to be used with the High Level API are defined here.
00026  */
00027 
00028 #ifndef SENSOR_DEBUG
00029 #define SENSOR_DEBUG
00030 #ifndef __KERNEL__
00031 #include <stdio.h>
00032 #include "host_serial.h"
00033 #endif
00034 #include "definitions.h"
00035 //Debug Enable Switch
00036 #define DEBUG_ENABLE                             1  /*!< Set to 1 to enable Function Logging feature */
00037 #define I2CLOG_ENABLE                            0  /*!< Set to 1 to enable I2C Logging feature */
00038 
00039 /* Error code definition */
00040 #define SENSOR_ERROR_NONE                        0  /*!< No error, Function executed successfully */
00041 #define SENSOR_ERROR                             1  /*!< Generic error code */
00042 
00043 #define COMMON_ERROR_BASE                       0x0100 /*!< Base number for all errors common to all function */
00044 #define COMMON_INVALID_PARAMS                   COMMON_ERROR_BASE +0x001 /*!< Provided Invalid params */
00045 #define COMMON_INVALID_OUTPUT                   COMMON_ERROR_BASE +0x002 /*!< Provided Invalid output */
00046 #define SYSTEM_ERROR_BASE                       0x0200 /*!< Base number for all errors related to system function */
00047 
00048 #define RANGE_ERROR_BASE                        0x0300 /*!< Base number for all errors related to ranging function */
00049 
00050 #define ALS_ERROR_BASE                          0x0400 /*!< Base number for all errors related to als function */
00051 
00052 #define DEBUG_SESSION_NOT_OPENE                 2
00053 #define DEBUG_ONLINE                            0x10 /*!< Run time debugging. output via usb-serial port */
00054 #define DEBUG_OFFLINE                           0x20 /*!< Offline debugging. Store debug log in memory space */
00055 
00056 /* Debugging api definition */
00057 #define MINIMUM_LOG_LEVEL                       0
00058 #define NORMAL_LOG_LEVEL                        1
00059 #define VERBOSE_LOG_LEVEL                       2
00060 #define I2C_LOG_LEVEL                           3
00061 
00062 
00063 #ifdef DEBUG_ENABLE
00064 
00065 extern char*    pDebugBuffer;
00066 extern uint32_t DebugLogSize;
00067 extern bool_t   DebugStarted;
00068 
00069 /* Defines for external use */
00070 #define SPRINTF(buf,fmt,args...) sprintf((char *)buf,fmt,##args)
00071 
00072 #define LOG_FUNCTION_START(...)  void* _pLogAllARgs_[]={ __VA_ARGS__ }; loggingFunctionStart(__func__, _pLogAllARgs_);
00073 #define LOG_FUNCTION_END(returned)   loggingFunctionEnd(__func__, returned, _pLogAllARgs_)
00074 
00075 
00076 #define DEBUG_WRITE_IN_LOG(...) SPRINTF(pDebugBuffer,##__VA_ARGS__); loggingOutput(pDebugBuffer);
00077 #define INTERNAL_DEBUG_LOG(...) if(DebugStarted){logDebugMessageStart(__func__);DEBUG_WRITE_IN_LOG(__VA_ARGS__);logDebugMessageEnd();}
00078 #define INTERNAL_ERROR_LOG(...) logErrorMessageStart(__func__);DEBUG_WRITE_IN_LOG(__VA_ARGS__);logErrorMessageEnd();
00079 
00080 #define DEBUG_LOG(...)   INTERNAL_DEBUG_LOG(__VA_ARGS__);CUSTOMER_DEBUG_LOG(__VA_ARGS__)
00081 #define SENSOR_ERROR_LOG(...)  INTERNAL_ERROR_LOG(__VA_ARGS__);CUSTOMER_ERROR_LOG(__VA_ARGS__)
00082 
00083 /*  Help compiling in C++  */
00084 #ifdef __cplusplus
00085 extern "C"{
00086 #endif   /*__cplusplus*/
00087 
00088 
00089 /*!
00090  * \fn          sensor_error loggingOpen()
00091  * \brief       Initialize debug sequence
00092  *
00093  * This function should be called at the beginning of the debugging session. It initializes everything that is necessary.
00094  * This function allocates a big size buffer in order to store all logged data.
00095  * \retval      SENSOR_ERROR_NONE : Success
00096  * \retval      "Other Error Code" : Failure
00097  */
00098 sensor_error loggingOpen();
00099 
00100 /*!
00101  * \fn          sensor_error loggingClose()
00102  * \brief       Initialize debug sequence
00103  *
00104  * This function shall be called once logging functionalities are no more required.
00105  * This function will free the memory allocated during the call to logingOpen function
00106  * \retval      SENSOR_ERROR_NONE : Success
00107  * \retval      "Other Error Code" : Failure
00108  */
00109 sensor_error loggingClose();
00110 
00111 /*!
00112  * \fn          sensor_error loggingSetMode()
00113  * \brief       Set up debug mode
00114  *
00115  * This function shall be called before start logging functions.
00116  * This function will set the debug logging mode as realtime output or offline mode.
00117  * \param[in]   mode
00118  * \retval      SENSOR_ERROR_NONE : Success
00119  * \retval      "Other Error Code" : Failure
00120  */
00121 sensor_error loggingSetMode(char mode);
00122 
00123 /*!
00124  * \fn          sensor_error loggingSetBuffer()
00125  * \brief       Set up offline debug buffer
00126  *
00127  * This function shall be called to set up offline debug buffer.
00128  * This function will use the buffer created from user application to store the logging data.
00129  * \param[in]   pBuf pointer of user buffer 
00130  * \param[in]   size size of user buffer
00131  * \retval      SENSOR_ERROR_NONE : Success
00132  * \retval      "Other Error Code" : Failure
00133  */
00134 sensor_error loggingSetBuffer(char *pBuf, uint32_t size);
00135 
00136 /*!
00137  * \fn          sensor_error loggingStart(uint8_t DebugLevel)
00138  * \brief       Start logging all activities
00139  *
00140  * All device activity will be logged once this function is called.
00141  * This function shall be called after loggingOpen().
00142  * \param[in]   DebugLevel
00143  * \retval      SENSOR_ERROR_NONE : Success
00144  * \retval      "Other Error Code" : Failure
00145  */
00146 sensor_error loggingStart(uint8_t DebugLevel);
00147 
00148 /*!
00149  * \fn          sensor_error loggingStop()
00150  * \brief       Stop logging all activities
00151  *
00152  * All device activity will stop to be logged once this function is called.
00153  * This function shall be called after  loggingStart().
00154  * \retval      SENSOR_ERROR_NONE : Success
00155  * \retval      "Other Error Code" : Failure
00156  */
00157 sensor_error loggingStop();
00158 
00159 /*!
00160  * \fn          sensor_error logDebugMessageStart(const char* pFunctionName)
00161  * \brief       Write start section to log debug message
00162  * \param[in]   pFunctionName
00163  * \retval      SENSOR_ERROR_NONE : Success
00164  * \retval      "Other Error Code" : Failure
00165  */
00166 sensor_error logDebugMessageStart(const char* pFunctionName);
00167 
00168 /*!
00169  * \fn          sensor_error logDebugMessageEnd()
00170  * \brief       Write end section to log debug message
00171  * \retval      SENSOR_ERROR_NONE : Success
00172  * \retval      "Other Error Code" : Failure
00173  */
00174 sensor_error logDebugMessageEnd();
00175 
00176 /*!
00177  * \fn          sensor_error logErrorMessageStart(const char* pFunctionName)
00178  * \brief       Write start section to log error message
00179  * \param[in]   pFunctionName
00180  * \retval      SENSOR_ERROR_NONE : Success
00181  * \retval      "Other Error Code" : Failure
00182  */
00183 sensor_error logErrorMessageStart(const char* pFunctionName);
00184 
00185 /*!
00186  * \fn          sensor_error logErrorMessageEnd()
00187  * \brief       Write end section to log error message
00188  * \retval      SENSOR_ERROR_NONE : Success
00189  * \retval      "Other Error Code" : Failure
00190  */
00191 sensor_error logErrorMessageEnd();
00192 
00193 /*!
00194  * \fn          sensor_error loggingFunctionStart(const char* FunctionName, void **pFuncArguments)
00195  * \brief       log start of an API function
00196  * \param[in]   FunctionName
00197  * \param[in]   pFuncArguments
00198  * \retval      SENSOR_ERROR_NONE : Success
00199  * \retval      "Other Error Code" : Failure
00200  */
00201 sensor_error loggingFunctionStart(const char* pFunctionName, void **pFuncArguments);
00202 
00203 /*!
00204  * \fn          sensor_error loggingFunctionEnd(const char* pFunctionName, sensor_error ReturnedValue, void **pFuncArguments)
00205  * \brief       log end of an API function
00206  * \param[in]   pFunctionName
00207  * \param[in]   ReturnedValue
00208  * \param[in]   pFuncArguments
00209  * \retval      SENSOR_ERROR_NONE : Success
00210  * \retval      "Other Error Code" : Failure
00211  */
00212 sensor_error loggingFunctionEnd(const char* pFunctionName, sensor_error ReturnedValue, void **pFuncArguments);
00213 
00214 /*!
00215  * \fn          sensor_error loggingOutput(char* pBuffer)
00216  * \brief       Write messge bugger to actual output
00217  * \param[in]   pBuffer
00218  * \retval      SENSOR_ERROR_NONE : Success
00219  * \retval      "Other Error Code" : Failure
00220  */
00221 sensor_error loggingOutput(char* pBuffer);
00222 
00223 /*!
00224  * \fn          sensor_error loggingOfflineOutput()
00225  * \brief       Write messge bugger from offline buffer to actual output
00226  * \retval      SENSOR_ERROR_NONE : Success
00227  * \retval      "Other Error Code" : Failure
00228  */
00229 sensor_error loggingOfflineOutput();
00230 
00231 /* help compiling in C++  */
00232 #ifdef __cplusplus
00233 }
00234 #endif   /*__cplusplus*/
00235 
00236 
00237 #else
00238 
00239 #define SENSOR_ERROR_LOG(...)    ;
00240 #define DEBUG_LOG(...)           ;
00241 #define LOG_FUNCTION_START(...)  ;
00242 #define LOG_FUNCTION_END(...)    ;
00243 #define loggingOpen()            SENSOR_ERROR_NONE
00244 #define loggingClose()           SENSOR_ERROR_NONE
00245 #define loggingStart(...)        SENSOR_ERROR_NONE
00246 #define loggingStop()            SENSOR_ERROR_NONE
00247 #define loggingGetSize(...)      SENSOR_ERROR_NONE
00248 #define loggingReadBack(...)     SENSOR_ERROR_NONE
00249 #define loggingOutput(...)       SENSOR_ERROR_NONE
00250 #endif
00251 
00252 #endif  /* DEBUG */
00253 
00254