2 * Amazon FreeRTOS Common V1.0.0
\r
3 * Copyright (C) 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
\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
12 * The above copyright notice and this permission notice shall be included in all
\r
13 * copies or substantial portions of the Software.
\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
22 * http://aws.amazon.com/freertos
\r
23 * http://www.FreeRTOS.org
\r
27 * @file iot_logging_setup.h
\r
28 * @brief Defines the logging macro #IotLog.
\r
31 #ifndef IOT_LOGGING_SETUP_H_
\r
32 #define IOT_LOGGING_SETUP_H_
\r
34 /* The config header is always included first. */
\r
35 #include "iot_config.h"
\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
42 * @functionpage{IotLog,logging,log}
\r
43 * @functionpage{IotLog_PrintBuffer,logging,printbuffer}
\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
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
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
60 * This logging function also has the following abbreviated forms that can be used
\r
61 * when an #IotLogConfig_t isn't needed.
\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
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
74 * @param[in] ... Message and format specification.
\r
76 * @return No return value. On errors, it prints nothing.
\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
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
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
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
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
101 * @param[in] pHeader A message to log before the buffer. Optional; pass `NULL`
\r
103 * @param[in] pBuffer Pointer to start of buffer.
\r
104 * @param[in] bufferSize Size of `pBuffer`.
\r
106 * @return No return value. On errors, it prints nothing.
\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
118 * const uint8_t pBuffer[] = { 0x00, 0x01, 0x02, 0x03 };
\r
120 * IotLog_PrintBuffer( "This buffer contains:",
\r
124 * The code above prints something like the following:
\r
126 * [DEBUG][LIB_NAME][2018-01-01 12:00:00] This buffer contains:
\r
132 * @def IotLogError( ... )
\r
133 * @brief Abbreviated logging macro for level #IOT_LOG_ERROR.
\r
137 * IotLog( IOT_LOG_ERROR, NULL, ... )
\r
142 * @def IotLogWarn( ... )
\r
143 * @brief Abbreviated logging macro for level #IOT_LOG_WARN.
\r
147 * IotLog( IOT_LOG_WARN, NULL, ... )
\r
152 * @def IotLogInfo( ... )
\r
153 * @brief Abbreviated logging macro for level #IOT_LOG_INFO.
\r
157 * IotLog( IOT_LOG_INFO, NULL, ... )
\r
162 * @def IotLogDebug( ... )
\r
163 * @brief Abbreviated logging macro for level #IOT_LOG_DEBUG.
\r
167 * IotLog( IOT_LOG_DEBUG, NULL, ... )
\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
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
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
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
206 #define IotLog_PrintBuffer( pHeader, pBuffer, bufferSize )
\r
208 /* Remove references to IotLog from the source code if logging is disabled. */
\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
223 #endif /* ifndef IOT_LOGGING_SETUP_H_ */
\r