hal_log.h

Go to the documentation of this file.

#ifndef HAL_LOG_H_
#define HAL_LOG_H_

#include "hal_config.h"
#include "hal_iodevice.h"
#include <stdint.h>
#include <stdbool.h>
#include <inttypes.h>

#if 1 == HAL_ENABLE_OS
#include "hal_os.h"
typedef OSTime HAL_LOG_Time;
#else
typedef uint32_t HAL_LOG_Time;
#endif

#ifndef HAL_ENABLE_LOG
    #define HAL_ENABLE_LOG 0
#endif // #ifndef HAL_ENABLE_LOG

#ifndef HAL_LOG_LAST_CHANNEL
  #define HAL_LOG_LAST_CHANNEL 0 // The default channel count is 1 (DEFAULT) since last channel is 0
#endif // #ifndef HAL_LOG_LAST_CHANNEL

#ifndef HAL_LOG_CHANNEL
  #define HAL_LOG_CHANNEL DEFAULT
#endif // #ifndef HAL_LOG_CHANNEL

#ifndef DEFAULT_LOG_CHANNEL
  #define DEFAULT_LOG_CHANNEL 0
#elif DEFAULT_LOG_CHANNEL != 0
  #error DEFAULT_LOG_CHANNEL redefined to non-zero value!
#endif // #ifndef DEFAULT_LOG_CHANNEL

#ifndef HAL_LOG_LEVEL
  #define HAL_LOG_LEVEL HAL_LOG_LEVEL_NOTICE // The default log verbosity
#endif // #ifndef HAL_LOG_LEVEL

// Definitions of valid log levels (according to syslog)
#define HAL_LOG_LEVEL_EMERGENCY 0
#define HAL_LOG_LEVEL_ALERT 1
#define HAL_LOG_LEVEL_CRITICAL 2
#define HAL_LOG_LEVEL_ERROR 3
#define HAL_LOG_LEVEL_WARNING 4
#define HAL_LOG_LEVEL_NOTICE 5
#define HAL_LOG_LEVEL_INFO 6
#define HAL_LOG_LEVEL_DEBUG 7

// The usage of the macros below is similar to csdio's printf function:
// The first argument is the format string, the latter arguments should be variables that will be substituted in the format string
#define HAL_LOG_EMERGENCY(...) HAL_LOG(HAL_LOG_LEVEL_EMERGENCY, __VA_ARGS__)
#define HAL_LOG_ALERT(...)     HAL_LOG(HAL_LOG_LEVEL_ALERT, __VA_ARGS__)
#define HAL_LOG_CRITICAL(...)  HAL_LOG(HAL_LOG_LEVEL_CRITICAL, __VA_ARGS__)
#define HAL_LOG_ERROR(...)     HAL_LOG(HAL_LOG_LEVEL_ERROR, __VA_ARGS__)
#define HAL_LOG_WARNING(...)   HAL_LOG(HAL_LOG_LEVEL_WARNING, __VA_ARGS__)
#define HAL_LOG_NOTICE(...)    HAL_LOG(HAL_LOG_LEVEL_NOTICE, __VA_ARGS__)
#define HAL_LOG_INFO(...)      HAL_LOG(HAL_LOG_LEVEL_INFO, __VA_ARGS__)
#define HAL_LOG_DEBUG(...)     HAL_LOG(HAL_LOG_LEVEL_DEBUG, __VA_ARGS__)

#define HAL_ASSERT(condition) if(!(condition)) do { HAL_LOG_CRITICAL("Assertion failed in " __FILE__ ":%u\n", __LINE__); } while(0)
#define HAL_ASSERT_AND_EXECUTE(condition) HAL_ASSERT(condition); else






bool HAL_LOG_SetChannelOutput(const uint8_t channel, IODevice const iodev);


bool HAL_LOG_SetChannelTimeSource(const uint8_t channel, HAL_LOG_Time (*timeSourceFunction)(void));


bool HAL_LOG_EnableChannel(const uint8_t channel);


bool HAL_LOG_DisableChannel(const uint8_t channel);


bool HAL_LOG_IsChannelEnabled(const uint8_t channel);


// The content below must NOT be altered (unless you are a developer or the almighty guinea pig)

#if 1 == HAL_ENABLE_LOG
   // Sanity checks
   #if (HAL_LOG_LAST_CHANNEL < UINT16_MIN) || (HAL_LOG_LAST_CHANNEL > (UINT16_MAX - 1))
     #error HAL_LOG_MAX_CHANNEL_NUMBER is outside of bounds
   #endif // #if (HAL_LOG_LAST_CHANNEL < UINT16_MIN) || (HAL_LOG_LAST_CHANNEL > (UINT16_MAX - 1))

   #if (HAL_LOG_LEVEL < HAL_LOG_LEVEL_EMERGENCY) || (HAL_LOG_LEVEL > HAL_LOG_LEVEL_DEBUG)
     #error HAL_LOG_LEVEL is outside of bounds
   #endif // #if (HAL_LOG_LEVEL < HAL_LOG_LEVEL_EMERGENCY) || (HAL_LOG_LEVEL > HAL_LOG_LEVEL_DEBUG)

   // Define helper macros
   #define HALI_STR(x) HALI_STR1(x) // Stringifies macro (first level of indirection)
   #define HALI_STR1(x) #x // Stringifies macro (second level of indirection)
   #define CAT(x, y) CAT1(x, y) // Concatenates two macro (first level of indirection)
   #define CAT1(a, b) a ## b // Concatenates two macro (second level of indirection)
   #define SECOND(a1, a2, ...) a2 // Returns second argument
   #define IS_PROBE(...) SECOND(__VA_ARGS__, 0)
   #define PROBE() ~, 1
   #define NOT(x) IS_PROBE(CAT(NOT_, x)) // Logic negation of macro
   #define NOT_0 PROBE()
   #define BOOL(x) NOT(NOT(x)) // Returns logical value of the macro
   #define IF_ELSE(x) IF_ELSE1(BOOL(x)) // Compile time if statement. usage: IF_ELSE(x)(if_true)(else)
   #define IF_ELSE1(x) CAT1(IF_, x)
   #define IF_1(...) __VA_ARGS__ IF_1_ELSE
   #define IF_0(...)             IF_0_ELSE
   #define IF_1_ELSE(...)
   #define IF_0_ELSE(...) __VA_ARGS__


   // Verify if the log channel is enabled by macro ($HAL_LOG_CHANNEL)_LOG_CHANNEL_ENABLED (i.e.  APP_LOG_CHANNEL_ENABLED)
   // When the macro was defined and set to 1 (i.e. #define APP_LOG_CHANNEL_ENABLED 1) the value is 1
   // When the macro was defined and set to 0 (i.e. #define APP_LOG_CHANNEL_ENABLED 0) the value is 0
   // When the macro was NOT defined the value is 1
   // Notice that HAL_LOG_CHANNEL is always defined either explicitly, or by default to DEFAULT.
   #if 1 == IF_ELSE(CAT(HAL_LOG_CHANNEL, _LOG_CHANNEL_ENABLED))(1)(0)
      // Look for descriptor number for this channel (i.e. #define APP_LOG_CHANNEL 1)
      #define HALI_CHANNEL CAT(HAL_LOG_CHANNEL, _LOG_CHANNEL)
      // Check if using default channel - if not, perform sanity check on channel number
      // There is no need to check Default channel, as it is already verified
      #define HALI_IF_LOG_CHANNEL_DEFAULT 1
      #if (1 == CAT(HALI_IF_LOG_CHANNEL_, HAL_LOG_CHANNEL)) || (HALI_CHANNEL > 0)
         #if (HALI_CHANNEL <= HAL_LOG_LAST_CHANNEL)
            // Adjust the maximum log level at user's discretion (i.e #define APP_LOG_CHANNEL_LEVEL HAL_LOG_LEVEL_NOTICE)
            #define HALI_LOG_CHANNEL_LEVEL CAT(HAL_LOG_CHANNEL, _LOG_CHANNEL_LEVEL)
            #define HALI_LOG_IF_CHANNEL_LEVEL_0 1
            #if (1 == CAT(HALI_LOG_IF_CHANNEL_LEVEL_, HALI_LOG_CHANNEL_LEVEL)) || (HALI_LOG_CHANNEL_LEVEL > 0)
               #if HALI_LOG_CHANNEL_LEVEL <= HAL_LOG_LEVEL
                  #undef HAL_LOG_LEVEL
                  #define HAL_LOG_LEVEL HALI_LOG_CHANNEL_LEVEL
               #else
                  #warning ($HAL_LOG_CHANNEL)_LOG_CHANNEL_LEVEL is bigger than HAL_LOG_LEVEL - defaults to HAL_LOG_LEVEL
               #endif // #if HALI_LOG_CHANNEL_LEVEL <= HAL_LOG_LEVEL
            #endif // #if (1 == CAT(HALI_LOG_IF_CHANNEL_LEVEL_, HALI_LOG_CHANNEL_LEVEL)) || (HALI_LOG_CHANNEL_LEVEL > 0)
            #undef HALI_LOG_IF_CHANNEL_LEVEL_0

            // At this point, all requisitions to enable log CHANNEL have been met

            // Check if HAL_LOG_SUBCHANNEL macro was defined, that would indicate that this is a subchannel log
            #ifdef HAL_LOG_SUBCHANNEL
               // Verify if the log channel is enabled by macro ($HAL_LOG_CHANNEL)_($HAL_LOG_SUBCHANNEL)_LOG_SUBCHANNEL_ENABLED (i.e.  APP_FOO_LOG_SUBCHANNEL_ENABLED)
               // When the macro was defined and set to 1 (i.e. #define APP_FOO_LOG_CHANNEL_ENABLED 1) the value is 1
               // When the macro was defined and set to 0 (i.e. #define APP_FOO_LOG_CHANNEL_ENABLED 0) the value is 0
               // When the macro was NOT defined the value is 1
               #if 1 == IF_ELSE(CAT(CAT(CAT(HAL_LOG_CHANNEL, _), HAL_LOG_SUBCHANNEL), _LOG_SUBCHANNEL_ENABLED))(1)(0)
                  #define HALI_LOG_SUBCHANNEL_LEVEL CAT(CAT(CAT(HAL_LOG_CHANNEL, _), HAL_LOG_SUBCHANNEL), _LOG_SUBCHANNEL_LEVEL)
                  #define HALI_LOG_IF_SUBCHANNEL_LEVEL_0 1
                  #if (1 == CAT(HALI_LOG_IF_SUBCHANNEL_LEVEL_, HALI_LOG_SUBCHANNEL_LEVEL)) || (HALI_LOG_SUBCHANNEL_LEVEL > 0)
                     #if (HALI_LOG_SUBCHANNEL_LEVEL <= HAL_LOG_LEVEL)
                        #undef HAL_LOG_LEVEL
                        #define HAL_LOG_LEVEL HALI_LOG_SUBCHANNEL_LEVEL
                     #else
                        #warning ($HAL_LOG_CHANNEL)_($HAL_LOG_SUBCHANNEL)_LOG_SUBCHANNEL_LEVEL is bigger than HAL_LOG_LEVEL - defaults to HAL_LOG_LEVEL
                     #endif // (HALI_LOG_SUBCHANNEL_LEVEL <= HAL_LOG_LEVEL)
                  #endif // #if (1 == CAT(HALI_LOG_IF_SUBCHANNEL_LEVEL_, HALI_LOG_SUBCHANNEL_LEVEL)) || (HALI_LOG_SUBCHANNEL_LEVEL > 0)
                  #undef HALI_LOG_IF_CHANNEL_LEVEL_0

                  #define HALI_LOG_HEADER CAT(CAT(HAL_LOG_CHANNEL, _), HAL_LOG_SUBCHANNEL)
                  #define HALI_LOG_ENABLED 1
               #endif // #if 1 == IF_ELSE(CAT(CAT(CAT(HAL_LOG_CHANNEL, _), HAL_LOG_SUBCHANNEL), _LOG_SUBCHANNEL_ENABLED))(1)(0)
            #else
               #define HALI_LOG_HEADER HAL_LOG_CHANNEL
               #define HALI_LOG_ENABLED 1
            #endif // #ifdef HAL_LOG_SUBCHANNEL
         #else
            #warning Channel descriptor (($HAL_LOG_CHANNEL)_LOG_CHANNEL) is bigger than HAL_LOG_LAST_CHANNEL - the channel will remain disabled
         #endif // #if (HALI_CHANNEL <= HAL_LOG_LAST_CHANNEL)
      #else
         #warning Channel descriptor ($HAL_LOG_CHANNEL)_LOG_CHANNEL_LEVEL not defined - the channel will remain disabled
      #endif // #if (1 == CAT(HALI_IF_LOG_CHANNEL_, HAL_LOG_CHANNEL)) || (HALI_CHANNEL > 0)
      #undef HALI_IF_LOG_CHANNEL_DEFAULT
   #endif // #if 1 == IF_ELSE(CAT(HAL_LOG_CHANNEL, _LOG_CHANNEL_ENABLED))(1)(0)
#endif // #if 1 == HAL_ENABLE_LOG

#if 1 == HALI_LOG_ENABLED
  void HAL_LOG_Log(const uint8_t channel, const uint8_t level, const char* const channelName, const HAL_LOG_Time timeout, const char* format, ...);
  #define HAL_LOG(level, ...) if(level <= HAL_LOG_LEVEL) HAL_LOG_Log(HALI_CHANNEL, UINT8_C(level), HALI_STR(HALI_LOG_HEADER), 0, __VA_ARGS__);
#else
  #define HAL_LOG(level, ...)
#endif // #if 1 == HALI_LOG_ENABLED

#endif // #ifndef HAL_LOG_H_