1 /* 2 * Copyright (c) 2017, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * This file define logging interface. 32 */ 33 #ifndef OTBR_COMMON_LOGGING_HPP_ 34 #define OTBR_COMMON_LOGGING_HPP_ 35 36 #include "openthread-br/config.h" 37 38 #include <stdarg.h> 39 #include <stddef.h> 40 41 #ifndef OTBR_LOG_TAG 42 #error "OTBR_LOG_TAG is not defined" 43 #endif 44 45 #include "common/types.hpp" 46 47 /** 48 * Logging level. 49 */ 50 typedef enum 51 { 52 OTBR_LOG_EMERG, ///< System is unusable 53 OTBR_LOG_ALERT, ///< Action must be taken immediately 54 OTBR_LOG_CRIT, ///< Critical conditions 55 OTBR_LOG_ERR, ///< Error conditions 56 OTBR_LOG_WARNING, ///< Warning conditions 57 OTBR_LOG_NOTICE, ///< Normal but significant condition 58 OTBR_LOG_INFO, ///< Informational 59 OTBR_LOG_DEBUG, ///< Debug level messages 60 } otbrLogLevel; 61 62 /** 63 * Get current log level. 64 */ 65 otbrLogLevel otbrLogGetLevel(void); 66 67 /** 68 * Get default log level. 69 */ 70 otbrLogLevel otbrLogGetDefaultLevel(void); 71 72 /** 73 * Set current log level. 74 */ 75 void otbrLogSetLevel(otbrLogLevel aLevel); 76 77 /** 78 * Control log to syslog. 79 * 80 * @param[in] aEnabled True to enable logging to/via syslog. 81 */ 82 void otbrLogSyslogSetEnabled(bool aEnabled); 83 84 /** 85 * This function initialize the logging service. 86 * 87 * @param[in] aProgramName The name of this runnable program. 88 * @param[in] aLevel Log level of the logger. 89 * @param[in] aPrintStderr Whether to log to stderr. 90 * @param[in] aSyslogDisable Whether to disable logging to syslog. 91 */ 92 void otbrLogInit(const char *aProgramName, otbrLogLevel aLevel, bool aPrintStderr, bool aSyslogDisable); 93 94 /** 95 * This function log at level @p aLevel. 96 * 97 * @param[in] aLevel Log level of the logger. 98 * @param[in] aLogTag Log tag. 99 * @param[in] aFormat Format string as in printf. 100 */ 101 void otbrLog(otbrLogLevel aLevel, const char *aLogTag, const char *aFormat, ...); 102 103 /** 104 * This function log at level @p aLevel. 105 * 106 * @param[in] aLevel Log level of the logger. 107 * @param[in] aFormat Format string as in printf. 108 * @param[in] aArgList The variable-length arguments list. 109 */ 110 void otbrLogv(otbrLogLevel aLevel, const char *aFormat, va_list aArgList); 111 112 /** 113 * This function writes logs without filtering with the log level. 114 * 115 * @param[in] aLevel Log level of the logger. 116 * @param[in] aFormat Format string as in printf. 117 * @param[in] aArgList The variable-length arguments list. 118 */ 119 void otbrLogvNoFilter(otbrLogLevel aLevel, const char *aFormat, va_list aArgList); 120 121 /** 122 * This function dump memory as hex string at level @p aLevel. 123 * 124 * @param[in] aLevel Log level of the logger. 125 * @param[in] aLogTag Log tag. 126 * @param[in] aPrefix String before dumping memory. 127 * @param[in] aMemory The pointer to the memory to be dumped. 128 * @param[in] aSize The size of memory in bytes to be dumped. 129 */ 130 void otbrDump(otbrLogLevel aLevel, const char *aLogTag, const char *aPrefix, const void *aMemory, size_t aSize); 131 132 /** 133 * This function converts error code to string. 134 * 135 * @param[in] aError The error code. 136 * 137 * @returns The string information of error. 138 */ 139 const char *otbrErrorString(otbrError aError); 140 141 /** 142 * This function deinitializes the logging service. 143 */ 144 void otbrLogDeinit(void); 145 146 /** 147 * This macro log an action result according to @p aError. 148 * 149 * If @p aError is OTBR_ERROR_NONE, the log level will be OTBR_LOG_INFO, 150 * otherwise OTBR_LOG_WARNING. 151 * 152 * @param[in] aError The action result. 153 * @param[in] aFormat Format string as in printf. 154 * @param[in] ... Arguments for the format specification. 155 */ 156 #define otbrLogResult(aError, aFormat, ...) \ 157 do \ 158 { \ 159 otbrError _err = (aError); \ 160 otbrLog(_err == OTBR_ERROR_NONE ? OTBR_LOG_INFO : OTBR_LOG_WARNING, OTBR_LOG_TAG, aFormat ": %s", \ 161 ##__VA_ARGS__, otbrErrorString(_err)); \ 162 } while (0) 163 164 /** 165 * @def otbrLogEmerg 166 * 167 * Log at level emergency. 168 * 169 * @param[in] ... Arguments for the format specification. 170 */ 171 172 /** 173 * @def otbrLogAlert 174 * 175 * Log at level alert. 176 * 177 * @param[in] ... Arguments for the format specification. 178 */ 179 180 /** 181 * @def otbrLogCrit 182 * 183 * Log at level critical. 184 * 185 * @param[in] ... Arguments for the format specification. 186 */ 187 188 /** 189 * @def otbrLogErr 190 * 191 * Log at level error. 192 * 193 * @param[in] ... Arguments for the format specification. 194 */ 195 196 /** 197 * @def otbrLogWarning 198 * 199 * Log at level warning. 200 * 201 * @param[in] ... Arguments for the format specification. 202 */ 203 204 /** 205 * @def otbrLogNotice 206 * 207 * Log at level notice. 208 * 209 * @param[in] ... Arguments for the format specification. 210 */ 211 212 /** 213 * @def otbrLogInfo 214 * 215 * Log at level information. 216 * 217 * @param[in] ... Arguments for the format specification. 218 */ 219 220 /** 221 * @def otbrLogDebug 222 * 223 * Log at level debug. 224 * 225 * @param[in] ... Arguments for the format specification. 226 */ 227 #define otbrLogEmerg(...) otbrLog(OTBR_LOG_EMERG, OTBR_LOG_TAG, __VA_ARGS__) 228 #define otbrLogAlert(...) otbrLog(OTBR_LOG_ALERT, OTBR_LOG_TAG, __VA_ARGS__) 229 #define otbrLogCrit(...) otbrLog(OTBR_LOG_CRIT, OTBR_LOG_TAG, __VA_ARGS__) 230 #define otbrLogErr(...) otbrLog(OTBR_LOG_ERR, OTBR_LOG_TAG, __VA_ARGS__) 231 #define otbrLogWarning(...) otbrLog(OTBR_LOG_WARNING, OTBR_LOG_TAG, __VA_ARGS__) 232 #define otbrLogNotice(...) otbrLog(OTBR_LOG_NOTICE, OTBR_LOG_TAG, __VA_ARGS__) 233 #define otbrLogInfo(...) otbrLog(OTBR_LOG_INFO, OTBR_LOG_TAG, __VA_ARGS__) 234 #define otbrLogDebug(...) otbrLog(OTBR_LOG_DEBUG, OTBR_LOG_TAG, __VA_ARGS__) 235 236 /** 237 * Convert otbrLogLevel to otLogLevel. 238 * 239 * @param[in] aLevel The otbrLogLevel to convert. 240 * 241 * @return the corresponding OT log level. 242 */ 243 otLogLevel ConvertToOtLogLevel(otbrLogLevel aLevel); 244 245 #endif // OTBR_COMMON_LOGGING_HPP_ 246