components/common/inc/log.h

   1 /******************************************************************************
   2  @file log.h
   3
   4  @brief TIMAC 2.0 API generic log to file or stream
   5
   6  Group: WCS LPC
   7  $Target Devices: Linux: AM335x, Embedded Devices: CC1310, CC1350, CC1352$
   8
   9  ******************************************************************************
  10  $License: BSD3 2016 $
  11
  12    Copyright (c) 2015, Texas Instruments Incorporated
  13    All rights reserved.
  14
  15    Redistribution and use in source and binary forms, with or without
  16    modification, are permitted provided that the following conditions
  17    are met:
  18
  19    *  Redistributions of source code must retain the above copyright
  20       notice, this list of conditions and the following disclaimer.
  21
  22    *  Redistributions in binary form must reproduce the above copyright
  23       notice, this list of conditions and the following disclaimer in the
  24       documentation and/or other materials provided with the distribution.
  25
  26    *  Neither the name of Texas Instruments Incorporated nor the names of
  27       its contributors may be used to endorse or promote products derived
  28       from this software without specific prior written permission.
  29
  30    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  31    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  32    THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  33    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  34    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  35    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  36    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  37    OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  38    WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  39    OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  40    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  41  ******************************************************************************
  42  $Release Name: TI-15.4Stack Linux x64 SDK$
  43  $Release Date: Sept 27, 2017 (2.04.00.13)$
  44  *****************************************************************************/
  45
  46 #if !defined(LOG_H)
  47 #define LOG_H
  48
  49 /*!
  50  * @file log.h
  51  *
  52  * @brief This handles all logging by the app
  53  */
  54 #include <stdint.h>
  55 #include <stddef.h>
  56 #include <stdbool.h>
  57 #include <stdarg.h>
  58 #include "compiler.h"
  59 #include "bitsnbits.h"
  60 #include "ini_file.h"
  61
  62 typedef int64_t logflags_t;
  63
  64 /* @struct LOG_cfg
  65  *
  66  * @brief Log configuration.
  67  */
  68 struct LOG_cfg {
  69     /*! typically a file or /dev/stderr */
  70     intptr_t log_stream;
  71
  72     /*! the filename we are logging to */
  73     const char *filename;
  74
  75     /*! what are we logging, see LOG_ALWAYS, or LOG_DBG_various, or others
  76      *
  77      * See LOG_test() for a description of how log flags work.
  78      */
  79     logflags_t log_flags;
  80
  81     /*! True if the log output should be sent to both a file and stderr */
  82     bool dup_to_stderr;
  83 };
  84
  85 /*
  86  * @def BUG_HERE
  87  * @hideinitializer
  88  *
  89  * Prints a debug message when a bug is discovered.
  90  */
  91 #define BUG_HERE(...)  \
  92     LOG_bug_here(__FILE__, __func__, __LINE__, __VA_ARGS__)
  93
  94 /*
  95  * @brief See macro: BUG_HERE(), Log a bug message, because something is wrong
  96  * @param file_name - filename, typically  __FILE__
  97  * @param func_name - function name, typically: from __func__
  98  * @param lineno - line number, typically from __line__
  99  * @param fmt - printf() format parameter
 100  *
 101  */
 102 void LOG_bug_here(const char *file_name,
 103                    const char *func_name,
 104                    int lineno,
 105                    const char *fmt, ...);
 106
 107 /*
 108  * @var LOG_cfg
 109  * @brief log configuration so you can modify the 'log_flags' on the fly.
 110  */
 111 extern struct LOG_cfg log_cfg;
 112
 113 /*!
 114  * @brief Determine if this "why" reason indicates we should log.
 115  *
 116  * @returns true if the log should occur or not.
 117  */
 118 bool LOG_test(logflags_t whybits);
 119
 120 /*!
 121  * @brief Setup the log, default is: /dev/stderr
 122  */
 123 void LOG_init(const char *filename);
 124
 125 /*!
 126  * @brief printf() a message to the log or not, via why bit or not
 127  *
 128  * @param whybits - Reason for log
 129  * @param fmt     - printf formatter.
 130  *
 131  * Internally, this uses LOG_Test() to determine if it should/ log or not.
 132  */
 133 void LOG_printf(logflags_t whybits,
 134                  _Printf_format_string_ const char *fmt, ...)
 135     __attribute__((format (printf,2,3)));
 136
 137 /*!
 138  * @brief print a log message, the unix errno an translated error message
 139  *
 140  * In this form:
 141  *
 142  * \code
 143  *     LOG_printf(LOG_ERROR "%s: (%d) %s\n", msg, errno, strerror(errno));
 144  * \endcode
 145  */
 146 void LOG_perror(const char *msg);
 147
 148 /*!
 149  * @brief print two log messages, the unix errno an translated error message
 150  *
 151  * In this form:
 152  *
 153  * \codes
 154  *     LOG_printf(LOG_ERROR,
 155  *                 "%s: %s (%d) %s\n",
 156  *                 msg1, msg2, errno,
 157  *                 strerror(errno));
 158  * \endcode
 159  */
 160 void LOG_perror2(const char *msg1, const char *msg2);
 161
 162 /*!
 163  * @brief Building block for LOG_printf()
 164  *
 165  * @param whybits - reason for log
 166  * @param fmt - printf format
 167  * @param ap - vararg list of paramters for fmt
 168  */
 169 void LOG_vprintf(logflags_t whybits, const char *fmt, va_list ap);
 170
 171 /*!
 172  * @brief Hexdump data to the log
 173  *
 174  * @param whybits - Parameter for LOG_test()
 175  * @param addr - address to print in hex dump
 176  * @param pBytes - data to print
 177  * @param nbytes - number of bytes to print
 178  *
 179  * @alsosee HEXLINE_Init() and HEXLINE_Format()
 180  */
 181 void LOG_hexdump(logflags_t whybits,
 182                  uint64_t addr,
 183                  const void *pBytes,
 184                  size_t nbytes);
 185
 186 /*
 187  * @brief Lock the log output over the course of several LOG_printf() messages
 188  *
 189  * Also see: LOG_UnLock()
 190  */
 191 void LOG_lock(void);
 192
 193 /*
 194  * @brief Unlock (after lockign) the log output
 195  *
 196  * Also see: LOG_Lock()
 197  */
 198 void LOG_unLock(void);
 199
 200 /*!
 201  * @brief close the log file
 202  *
 203  */
 204 void LOG_close(void);
 205
 206 #define LOG_ALWAYS 0         /*! override and log this */
 207 /* All DBG items should be specific bits! */
 208
 209 #define LOG_FATAL             _bit0
 210 #define LOG_ERROR             _bit1
 211 #define LOG_WARN              _bit2
 212 #define LOG_DBG_MUTEX         _bit3   /*! mutex debug messages enabled */
 213 #define LOG_DBG_THREAD        _bit4   /*! thread debug messages enabled */
 214 #define LOG_DBG_FIFO          _bit5   /*! fifo   debug messages enabled */
 215 #define LOG_DBG_UART          _bit6   /*! uart   debug messages enabled */
 216 #define LOG_DBG_UART_RAW      _bit7   /*! uart   debug (raw rd/wr bytes)*/
 217 #define LOG_DBG_SLEEP         _bit8   /*! sleep  debug messages enabled */
 218 #define LOG_DBG_SOCKET        _bit9   /*! socket debug messages enabled */
 219 #define LOG_DBG_SOCKET_RAW    _bit9   /*! socket debug messages enabled */
 220 #define LOG_DBG_COLLECTOR     _bit10  /*! Collector debug messages enabled */
 221 #define LOG_DBG_COLLECTOR_RAW _bit11  /*! Collector raw data debug messages enabled */
 222
 223 /* Bit ranges */
 224 #define LOG_DBG_NV_bitnum_first 12
 225 #define LOG_DBG_NV_bitnum_last  15
 226
 227 /* Bit ranges */
 228 #define LOG_DBG_MT_bitnum_first 16
 229 #define LOG_DBG_MT_bitnum_last  23
 230
 231 #define LOG_DBG_API_MAC_bitnum_first 24
 232 #define LOG_DBG_API_MAC_bitnum_last  27
 233
 234 /* Apps can use bit 32 ... and above */
 235 #define LOG_DBG_APP_bitnum_first  32
 236 #define LOG_DBG_APP_bitnum_last   62 /* Because the flags are *SIGNED* cannot use 63 */
 237
 238 /* if log_cfg.log_flags == EVERYTHING */
 239 /*    Then everything is logged */
 240 #define LOG_EVERYTHING -1 /*! used in log_cfg.log_flags Log everything */
 241 #define LOG_NOTHING    -2 /*! do not log anything */
 242
 243 /* forward decloration (see: ini_file.h) */
 244 struct ini_parser;
 245
 246 /*
 247  * @brief Handle INI File settings for logs
 248  * @param pINI - ini file parse information
 249  * @param handled - set to true if this settings was handled.
 250  * @returns negative if error
 251  *
 252  * This inside an INI file the following construct:
 253  *     [log]
 254  *        filename FILENAME
 255  *        flags    NUMBER or NAMES
 256  *
 257  * This specifies where the log will be written.
 258  * By default, there is no log.
 259  * FLAGS can be a number, or a series of names.
 260  * The work flags may be repeated multiple times
 261  * The flags are effectivly cumlative.
 262  */
 263
 264 int LOG_INI_settings(struct ini_parser *pINI, bool *handled);
 265
 266 /* forward decloration */
 267 struct ini_flag_name;
 268
 269 /*
 270  * @var log_flag_names
 271  * @brief list of appl log flag names, see LOG_INI_Settings() for more details.
 272  *
 273  * (this is a constant array, of pointers to constant structures)
 274  *
 275  * Note this array ends with a null pointer.
 276  * Each sub-array, ends with (pFlag->name == NULL)
 277  */
 278 extern const struct ini_flag_name * const log_flag_names[];
 279 /* @var log_builtin_flag_names
 280  * @brief Built in log names for various modules, see LOG_INI_Settings()
 281  */
 282 extern const struct ini_flag_name log_builtin_flag_names[];
 283 extern const struct ini_flag_name mt_msg_log_flags[];
 284 extern const struct ini_flag_name nv_log_flags[];
 285 extern const struct ini_flag_name api_mac_log_flags[];
 286
 287 #endif
 288
 289 /*
 290  *  ========================================
 291  *  Texas Instruments Micro Controller Style
 292  *  ========================================
 293  *  Local Variables:
 294  *  mode: c
 295  *  c-file-style: "bsd"
 296  *  tab-width: 4
 297  *  c-basic-offset: 4
 298  *  indent-tabs-mode: nil
 299  *  End:
 300  *  vim:set  filetype=c tabstop=4 shiftwidth=4 expandtab=true
 301  */