git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/c_sdk/standard/common/include/iot_logging_setup.h

   1 /*\r
   2  * Amazon FreeRTOS Common V1.0.0\r
   3  * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://aws.amazon.com/freertos\r
  23  * http://www.FreeRTOS.org\r
  24  */\r
  25 \r
  26 /**\r
  27  * @file iot_logging_setup.h\r
  28  * @brief Defines the logging macro #IotLog.\r
  29  */\r
  30 \r
  31 #ifndef IOT_LOGGING_SETUP_H_\r
  32 #define IOT_LOGGING_SETUP_H_\r
  33 \r
  34 /* The config header is always included first. */\r
  35 #include "iot_config.h"\r
  36 \r
  37 /* Logging include. Because it's included here, iot_logging.h never needs\r
  38  * to be included in source. */\r
  39 #include "private/iot_logging.h"\r
  40 \r
  41 /**\r
  42  * @functionpage{IotLog,logging,log}\r
  43  * @functionpage{IotLog_PrintBuffer,logging,printbuffer}\r
  44  */\r
  45 \r
  46 /**\r
  47  * @def IotLog( messageLevel, pLogConfig, ... )\r
  48  * @brief Logging function for a specific library. In most cases, this is the\r
  49  * logging function to call.\r
  50  *\r
  51  * This function prints a single log message. It is available when @ref\r
  52  * LIBRARY_LOG_LEVEL is not #IOT_LOG_NONE. Log messages automatically\r
  53  * include the [log level](@ref logging_constants_levels), [library name]\r
  54  * (@ref LIBRARY_LOG_NAME), and time. An optional @ref IotLogConfig_t may\r
  55  * be passed to this function to hide information for a single log message.\r
  56  *\r
  57  * The logging library must be set up before this function may be called. See\r
  58  * @ref logging_setup_use for more information.\r
  59  *\r
  60  * This logging function also has the following abbreviated forms that can be used\r
  61  * when an #IotLogConfig_t isn't needed.\r
  62  *\r
  63  * Name         | Equivalent to\r
  64  * ----         | -------------\r
  65  * #IotLogError | @code{c} IotLog( IOT_LOG_ERROR, NULL, ... ) @endcode\r
  66  * #IotLogWarn  | @code{c} IotLog( IOT_LOG_WARN, NULL, ... ) @endcode\r
  67  * #IotLogInfo  | @code{c} IotLog( IOT_LOG_INFO, NULL, ... ) @endcode\r
  68  * #IotLogDebug | @code{c} IotLog( IOT_LOG_DEBUG, NULL, ... ) @endcode\r
  69  *\r
  70  * @param[in] messageLevel Log level of this message. Must be one of the\r
  71  * @ref logging_constants_levels.\r
  72  * @param[in] pLogConfig Pointer to an #IotLogConfig_t. Optional; pass `NULL`\r
  73  * to ignore.\r
  74  * @param[in] ... Message and format specification.\r
  75  *\r
  76  * @return No return value. On errors, it prints nothing.\r
  77  *\r
  78  * @note This function may be implemented as a macro.\r
  79  * @see @ref logging_function_generic for the generic (not library-specific)\r
  80  * logging function.\r
  81  */\r
  82 \r
  83 /**\r
  84  * @def IotLog_PrintBuffer( pHeader, pBuffer, bufferSize )\r
  85  * @brief Log the contents of buffer as bytes. Only available when @ref\r
  86  * LIBRARY_LOG_LEVEL is #IOT_LOG_DEBUG.\r
  87  *\r
  88  * This function prints the bytes located at a given memory address. It is\r
  89  * intended for debugging only, and is therefore only available when @ref\r
  90  * LIBRARY_LOG_LEVEL is #IOT_LOG_DEBUG.\r
  91  *\r
  92  * Log messages printed by this function <b>always</b> include the [log level]\r
  93  * (@ref logging_constants_levels), [library name](@ref LIBRARY_LOG_NAME),\r
  94  * and time.  In addition, this function may print an optional header `pHeader`\r
  95  * before it prints the contents of the buffer. This function does not have an\r
  96  * #IotLogConfig_t parameter.\r
  97  *\r
  98  * The logging library must be set up before this function may be called. See\r
  99  * @ref logging_setup_use for more information.\r
 100  *\r
 101  * @param[in] pHeader A message to log before the buffer. Optional; pass `NULL`\r
 102  * to ignore.\r
 103  * @param[in] pBuffer Pointer to start of buffer.\r
 104  * @param[in] bufferSize Size of `pBuffer`.\r
 105  *\r
 106  * @return No return value. On errors, it prints nothing.\r
 107  *\r
 108  * @note This function may be implemented as a macro.\r
 109  * @note To conserve memory, @ref logging_function_genericprintbuffer (the underlying\r
 110  * implementation) only allocates enough memory for a single line of output. Therefore,\r
 111  * in multithreaded systems, its output may appear "fragmented" if other threads are\r
 112  * logging simultaneously.\r
 113  * @see @ref logging_function_genericprintbuffer for the generic (not library-specific)\r
 114  * buffer logging function.\r
 115  *\r
 116  * <b>Example</b>\r
 117  * @code{c}\r
 118  * const uint8_t pBuffer[] = { 0x00, 0x01, 0x02, 0x03 };\r
 119  *\r
 120  * IotLog_PrintBuffer( "This buffer contains:",\r
 121  *                     pBuffer,\r
 122  *                     4 );\r
 123  * @endcode\r
 124  * The code above prints something like the following:\r
 125  * @code{c}\r
 126  * [DEBUG][LIB_NAME][2018-01-01 12:00:00] This buffer contains:\r
 127  * 00 01 02 03\r
 128  * @endcode\r
 129  */\r
 130 \r
 131 /**\r
 132  * @def IotLogError( ...  )\r
 133  * @brief Abbreviated logging macro for level #IOT_LOG_ERROR.\r
 134  *\r
 135  * Equivalent to:\r
 136  * @code{c}\r
 137  * IotLog( IOT_LOG_ERROR, NULL, ... )\r
 138  * @endcode\r
 139  */\r
 140 \r
 141 /**\r
 142  * @def IotLogWarn( ...  )\r
 143  * @brief Abbreviated logging macro for level #IOT_LOG_WARN.\r
 144  *\r
 145  * Equivalent to:\r
 146  * @code{c}\r
 147  * IotLog( IOT_LOG_WARN, NULL, ... )\r
 148  * @endcode\r
 149  */\r
 150 \r
 151 /**\r
 152  * @def IotLogInfo( ...  )\r
 153  * @brief Abbreviated logging macro for level #IOT_LOG_INFO.\r
 154  *\r
 155  * Equivalent to:\r
 156  * @code{c}\r
 157  * IotLog( IOT_LOG_INFO, NULL, ... )\r
 158  * @endcode\r
 159  */\r
 160 \r
 161 /**\r
 162  * @def IotLogDebug( ...  )\r
 163  * @brief Abbreviated logging macro for level #IOT_LOG_DEBUG.\r
 164  *\r
 165  * Equivalent to:\r
 166  * @code{c}\r
 167  * IotLog( IOT_LOG_DEBUG, NULL, ... )\r
 168  * @endcode\r
 169  */\r
 170 \r
 171 /* Check that LIBRARY_LOG_LEVEL is defined and has a valid value. */\r
 172 #if !defined( LIBRARY_LOG_LEVEL ) ||            \\r
 173     ( LIBRARY_LOG_LEVEL != IOT_LOG_NONE &&  \\r
 174       LIBRARY_LOG_LEVEL != IOT_LOG_ERROR && \\r
 175       LIBRARY_LOG_LEVEL != IOT_LOG_WARN &&  \\r
 176       LIBRARY_LOG_LEVEL != IOT_LOG_INFO &&  \\r
 177       LIBRARY_LOG_LEVEL != IOT_LOG_DEBUG )\r
 178     #error "Please define LIBRARY_LOG_LEVEL as either IOT_LOG_NONE, IOT_LOG_ERROR, IOT_LOG_WARN, IOT_LOG_INFO, or IOT_LOG_DEBUG."\r
 179 /* Check that LIBRARY_LOG_NAME is defined and has a valid value. */\r
 180 #elif !defined( LIBRARY_LOG_NAME )\r
 181     #error "Please define LIBRARY_LOG_NAME."\r
 182 #else\r
 183     /* Define IotLog if the log level is greater than "none". */\r
 184     #if LIBRARY_LOG_LEVEL > IOT_LOG_NONE\r
 185         #define IotLog( messageLevel, pLogConfig, ... )   \\r
 186                 IotLog_Generic( LIBRARY_LOG_LEVEL,        \\r
 187                                 LIBRARY_LOG_NAME,        \\r
 188                                 messageLevel,             \\r
 189                                 pLogConfig,               \\r
 190                                 __VA_ARGS__ )\r
 191 \r
 192         /* Define the abbreviated logging macros. */\r
 193         #define IotLogError( ...  )    IotLog( IOT_LOG_ERROR, NULL, __VA_ARGS__ )\r
 194         #define IotLogWarn( ... )      IotLog( IOT_LOG_WARN, NULL, __VA_ARGS__ )\r
 195         #define IotLogInfo( ... )      IotLog( IOT_LOG_INFO, NULL, __VA_ARGS__ )\r
 196         #define IotLogDebug( ... )     IotLog( IOT_LOG_DEBUG, NULL, __VA_ARGS__ )\r
 197 \r
 198         /* If log level is DEBUG, enable the function to print buffers. */\r
 199         #if LIBRARY_LOG_LEVEL >= IOT_LOG_DEBUG\r
 200         #define IotLog_PrintBuffer( pHeader, pBuffer, bufferSize )    \\r
 201                 IotLog_GenericPrintBuffer( LIBRARY_LOG_NAME,         \\r
 202                                            pHeader,                   \\r
 203                                            pBuffer,                   \\r
 204                                            bufferSize )\r
 205         #else\r
 206         #define IotLog_PrintBuffer( pHeader, pBuffer, bufferSize )\r
 207         #endif\r
 208     /* Remove references to IotLog from the source code if logging is disabled. */\r
 209     #else\r
 210         /* @[declare_logging_log] */\r
 211         #define IotLog( messageLevel, pLogConfig, ... )\r
 212         /* @[declare_logging_log] */\r
 213         /* @[declare_logging_printbuffer] */\r
 214         #define IotLog_PrintBuffer( pHeader, pBuffer, bufferSize )\r
 215         /* @[declare_logging_printbuffer] */\r
 216         #define IotLogError( ...  )\r
 217         #define IotLogWarn( ... )\r
 218         #define IotLogInfo( ... )\r
 219         #define IotLogDebug( ... )\r
 220     #endif\r
 221 #endif\r
 222 \r
 223 #endif /* ifndef IOT_LOGGING_SETUP_H_ */\r