1 /* 2 * Copyright (c) 2018 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_LOGGING_LOG_H_ 8 #define ZEPHYR_INCLUDE_LOGGING_LOG_H_ 9 10 #include <zephyr/logging/log_instance.h> 11 #include <zephyr/logging/log_core.h> 12 #include <zephyr/sys/iterable_sections.h> 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /** 19 * @brief Logging 20 * @defgroup logging Logging 21 * @ingroup os_services 22 * @{ 23 * @} 24 */ 25 26 /** 27 * @brief Logger API 28 * @defgroup log_api Logging API 29 * @ingroup logger 30 * @{ 31 */ 32 33 /** 34 * @brief Writes an ERROR level message to the log. 35 * 36 * @details It's meant to report severe errors, such as those from which it's 37 * not possible to recover. 38 * 39 * @param ... A string optionally containing printk valid conversion specifier, 40 * followed by as many values as specifiers. 41 */ 42 #define LOG_ERR(...) Z_LOG(LOG_LEVEL_ERR, __VA_ARGS__) 43 44 /** 45 * @brief Writes a WARNING level message to the log. 46 * 47 * @details It's meant to register messages related to unusual situations that 48 * are not necessarily errors. 49 * 50 * @param ... A string optionally containing printk valid conversion specifier, 51 * followed by as many values as specifiers. 52 */ 53 #define LOG_WRN(...) Z_LOG(LOG_LEVEL_WRN, __VA_ARGS__) 54 55 /** 56 * @brief Writes an INFO level message to the log. 57 * 58 * @details It's meant to write generic user oriented messages. 59 * 60 * @param ... A string optionally containing printk valid conversion specifier, 61 * followed by as many values as specifiers. 62 */ 63 #define LOG_INF(...) Z_LOG(LOG_LEVEL_INF, __VA_ARGS__) 64 65 /** 66 * @brief Writes a DEBUG level message to the log. 67 * 68 * @details It's meant to write developer oriented information. 69 * 70 * @param ... A string optionally containing printk valid conversion specifier, 71 * followed by as many values as specifiers. 72 */ 73 #define LOG_DBG(...) Z_LOG(LOG_LEVEL_DBG, __VA_ARGS__) 74 75 /** 76 * @brief Unconditionally print raw log message. 77 * 78 * The result is same as if printk was used but it goes through logging 79 * infrastructure thus utilizes logging mode, e.g. deferred mode. 80 * 81 * @param ... A string optionally containing printk valid conversion specifier, 82 * followed by as many values as specifiers. 83 */ 84 #define LOG_PRINTK(...) Z_LOG_PRINTK(0, __VA_ARGS__) 85 86 /** 87 * @brief Unconditionally print raw log message. 88 * 89 * Provided string is printed as is without appending any characters (e.g., color or newline). 90 * 91 * @param ... A string optionally containing printk valid conversion specifier, 92 * followed by as many values as specifiers. 93 */ 94 #define LOG_RAW(...) Z_LOG_PRINTK(1, __VA_ARGS__) 95 96 /** 97 * @brief Writes an ERROR level message associated with the instance to the log. 98 * 99 * Message is associated with specific instance of the module which has 100 * independent filtering settings (if runtime filtering is enabled) and 101 * message prefix (\<module_name\>.\<instance_name\>). It's meant to report 102 * severe errors, such as those from which it's not possible to recover. 103 * 104 * @param _log_inst Pointer to the log structure associated with the instance. 105 * @param ... A string optionally containing printk valid conversion specifier, 106 * followed by as many values as specifiers. 107 */ 108 #define LOG_INST_ERR(_log_inst, ...) \ 109 Z_LOG_INSTANCE(LOG_LEVEL_ERR, _log_inst, __VA_ARGS__) 110 111 /** 112 * @brief Writes a WARNING level message associated with the instance to the 113 * log. 114 * 115 * Message is associated with specific instance of the module which has 116 * independent filtering settings (if runtime filtering is enabled) and 117 * message prefix (\<module_name\>.\<instance_name\>). It's meant to register 118 * messages related to unusual situations that are not necessarily errors. 119 * 120 * @param _log_inst Pointer to the log structure associated with the instance. 121 * @param ... A string optionally containing printk valid conversion 122 * specifier, followed by as many values as specifiers. 123 */ 124 #define LOG_INST_WRN(_log_inst, ...) \ 125 Z_LOG_INSTANCE(LOG_LEVEL_WRN, _log_inst, __VA_ARGS__) 126 127 /** 128 * @brief Writes an INFO level message associated with the instance to the log. 129 * 130 * Message is associated with specific instance of the module which has 131 * independent filtering settings (if runtime filtering is enabled) and 132 * message prefix (\<module_name\>.\<instance_name\>). It's meant to write 133 * generic user oriented messages. 134 * 135 * @param _log_inst Pointer to the log structure associated with the instance. 136 * @param ... A string optionally containing printk valid conversion specifier, 137 * followed by as many values as specifiers. 138 */ 139 #define LOG_INST_INF(_log_inst, ...) \ 140 Z_LOG_INSTANCE(LOG_LEVEL_INF, _log_inst, __VA_ARGS__) 141 142 /** 143 * @brief Writes a DEBUG level message associated with the instance to the log. 144 * 145 * Message is associated with specific instance of the module which has 146 * independent filtering settings (if runtime filtering is enabled) and 147 * message prefix (\<module_name\>.\<instance_name\>). It's meant to write 148 * developer oriented information. 149 * 150 * @param _log_inst Pointer to the log structure associated with the instance. 151 * @param ... A string optionally containing printk valid conversion specifier, 152 * followed by as many values as specifiers. 153 */ 154 #define LOG_INST_DBG(_log_inst, ...) \ 155 Z_LOG_INSTANCE(LOG_LEVEL_DBG, _log_inst, __VA_ARGS__) 156 157 /** 158 * @brief Writes an ERROR level hexdump message to the log. 159 * 160 * @details It's meant to report severe errors, such as those from which it's 161 * not possible to recover. 162 * 163 * @param _data Pointer to the data to be logged. 164 * @param _length Length of data (in bytes). 165 * @param _str Persistent, raw string. 166 */ 167 #define LOG_HEXDUMP_ERR(_data, _length, _str) \ 168 Z_LOG_HEXDUMP(LOG_LEVEL_ERR, _data, _length, _str) 169 170 /** 171 * @brief Writes a WARNING level message to the log. 172 * 173 * @details It's meant to register messages related to unusual situations that 174 * are not necessarily errors. 175 * 176 * @param _data Pointer to the data to be logged. 177 * @param _length Length of data (in bytes). 178 * @param _str Persistent, raw string. 179 */ 180 #define LOG_HEXDUMP_WRN(_data, _length, _str) \ 181 Z_LOG_HEXDUMP(LOG_LEVEL_WRN, _data, _length, _str) 182 183 /** 184 * @brief Writes an INFO level message to the log. 185 * 186 * @details It's meant to write generic user oriented messages. 187 * 188 * @param _data Pointer to the data to be logged. 189 * @param _length Length of data (in bytes). 190 * @param _str Persistent, raw string. 191 */ 192 #define LOG_HEXDUMP_INF(_data, _length, _str) \ 193 Z_LOG_HEXDUMP(LOG_LEVEL_INF, _data, _length, _str) 194 195 /** 196 * @brief Writes a DEBUG level message to the log. 197 * 198 * @details It's meant to write developer oriented information. 199 * 200 * @param _data Pointer to the data to be logged. 201 * @param _length Length of data (in bytes). 202 * @param _str Persistent, raw string. 203 */ 204 #define LOG_HEXDUMP_DBG(_data, _length, _str) \ 205 Z_LOG_HEXDUMP(LOG_LEVEL_DBG, _data, _length, _str) 206 207 /** 208 * @brief Writes an ERROR hexdump message associated with the instance to the 209 * log. 210 * 211 * Message is associated with specific instance of the module which has 212 * independent filtering settings (if runtime filtering is enabled) and 213 * message prefix (\<module_name\>.\<instance_name\>). It's meant to report 214 * severe errors, such as those from which it's not possible to recover. 215 * 216 * @param _log_inst Pointer to the log structure associated with the instance. 217 * @param _data Pointer to the data to be logged. 218 * @param _length Length of data (in bytes). 219 * @param _str Persistent, raw string. 220 */ 221 #define LOG_INST_HEXDUMP_ERR(_log_inst, _data, _length, _str) \ 222 Z_LOG_HEXDUMP_INSTANCE(LOG_LEVEL_ERR, _log_inst, _data, _length, _str) 223 224 /** 225 * @brief Writes a WARNING level hexdump message associated with the instance to 226 * the log. 227 * 228 * @details It's meant to register messages related to unusual situations that 229 * are not necessarily errors. 230 * 231 * @param _log_inst Pointer to the log structure associated with the instance. 232 * @param _data Pointer to the data to be logged. 233 * @param _length Length of data (in bytes). 234 * @param _str Persistent, raw string. 235 */ 236 #define LOG_INST_HEXDUMP_WRN(_log_inst, _data, _length, _str) \ 237 Z_LOG_HEXDUMP_INSTANCE(LOG_LEVEL_WRN, _log_inst, _data, _length, _str) 238 239 /** 240 * @brief Writes an INFO level hexdump message associated with the instance to 241 * the log. 242 * 243 * @details It's meant to write generic user oriented messages. 244 * 245 * @param _log_inst Pointer to the log structure associated with the instance. 246 * @param _data Pointer to the data to be logged. 247 * @param _length Length of data (in bytes). 248 * @param _str Persistent, raw string. 249 */ 250 #define LOG_INST_HEXDUMP_INF(_log_inst, _data, _length, _str) \ 251 Z_LOG_HEXDUMP_INSTANCE(LOG_LEVEL_INF, _log_inst, _data, _length, _str) 252 253 /** 254 * @brief Writes a DEBUG level hexdump message associated with the instance to 255 * the log. 256 * 257 * @details It's meant to write developer oriented information. 258 * 259 * @param _log_inst Pointer to the log structure associated with the instance. 260 * @param _data Pointer to the data to be logged. 261 * @param _length Length of data (in bytes). 262 * @param _str Persistent, raw string. 263 */ 264 #define LOG_INST_HEXDUMP_DBG(_log_inst, _data, _length, _str) \ 265 Z_LOG_HEXDUMP_INSTANCE(LOG_LEVEL_DBG, _log_inst, _data, _length, _str) 266 267 /** 268 * @brief Writes an formatted string to the log. 269 * 270 * @details Conditionally compiled (see CONFIG_LOG_PRINTK). Function provides 271 * printk functionality. 272 * 273 * It is less efficient compared to standard logging because static packaging 274 * cannot be used. 275 * 276 * @param fmt Formatted string to output. 277 * @param ap Variable parameters. 278 */ 279 void z_log_vprintk(const char *fmt, va_list ap); 280 281 #ifdef __cplusplus 282 } 283 #define LOG_IN_CPLUSPLUS 1 284 #endif 285 /* Macro expects that optionally on second argument local log level is provided. 286 * If provided it is returned, otherwise default log level is returned or 287 * LOG_LEVEL, if it was locally defined. 288 */ 289 #if !defined(CONFIG_LOG) 290 #define _LOG_LEVEL_RESOLVE(...) LOG_LEVEL_NONE 291 #else 292 #define _LOG_LEVEL_RESOLVE(...) \ 293 Z_LOG_EVAL(LOG_LEVEL, \ 294 (GET_ARG_N(2, __VA_ARGS__, LOG_LEVEL)), \ 295 (GET_ARG_N(2, __VA_ARGS__, CONFIG_LOG_DEFAULT_LEVEL))) 296 #endif 297 298 /* Return first argument */ 299 #define _LOG_ARG1(arg1, ...) arg1 300 301 #define _LOG_MODULE_CONST_DATA_CREATE(_name, _level) \ 302 IF_ENABLED(LOG_IN_CPLUSPLUS, (extern)) \ 303 const STRUCT_SECTION_ITERABLE_ALTERNATE(log_const, \ 304 log_source_const_data, \ 305 Z_LOG_ITEM_CONST_DATA(_name)) = \ 306 { \ 307 .name = STRINGIFY(_name), \ 308 .level = _level \ 309 } 310 311 #define _LOG_MODULE_DYNAMIC_DATA_CREATE(_name) \ 312 STRUCT_SECTION_ITERABLE_ALTERNATE(log_dynamic, log_source_dynamic_data, \ 313 LOG_ITEM_DYNAMIC_DATA(_name)) 314 315 #define _LOG_MODULE_DYNAMIC_DATA_COND_CREATE(_name) \ 316 IF_ENABLED(CONFIG_LOG_RUNTIME_FILTERING, \ 317 (_LOG_MODULE_DYNAMIC_DATA_CREATE(_name);)) 318 319 #define _LOG_MODULE_DATA_CREATE(_name, _level) \ 320 _LOG_MODULE_CONST_DATA_CREATE(_name, _level); \ 321 _LOG_MODULE_DYNAMIC_DATA_COND_CREATE(_name) 322 323 /* Determine if data for the module shall be created. It is created if logging 324 * is enabled, override level is set or module specific level is set (not off). 325 */ 326 #define Z_DO_LOG_MODULE_REGISTER(...) \ 327 Z_LOG_EVAL(CONFIG_LOG_OVERRIDE_LEVEL, \ 328 (1), \ 329 (Z_LOG_EVAL(_LOG_LEVEL_RESOLVE(__VA_ARGS__), (1), (0))) \ 330 ) 331 332 /** 333 * @brief Create module-specific state and register the module with Logger. 334 * 335 * This macro normally must be used after including <zephyr/logging/log.h> to 336 * complete the initialization of the module. 337 * 338 * Module registration can be skipped in two cases: 339 * 340 * - The module consists of more than one file, and another file 341 * invokes this macro. (LOG_MODULE_DECLARE() should be used instead 342 * in all of the module's other files.) 343 * - Instance logging is used and there is no need to create module entry. In 344 * that case LOG_LEVEL_SET() should be used to set log level used within the 345 * file. 346 * 347 * Macro accepts one or two parameters: 348 * - module name 349 * - optional log level. If not provided then default log level is used in 350 * the file. 351 * 352 * Example usage: 353 * - LOG_MODULE_REGISTER(foo, CONFIG_FOO_LOG_LEVEL) 354 * - LOG_MODULE_REGISTER(foo) 355 * 356 * 357 * @note The module's state is defined, and the module is registered, 358 * only if LOG_LEVEL for the current source file is non-zero or 359 * it is not defined and CONFIG_LOG_DEFAULT_LEVEL is non-zero. 360 * In other cases, this macro has no effect. 361 * @see LOG_MODULE_DECLARE 362 */ 363 #define LOG_MODULE_REGISTER(...) \ 364 COND_CODE_1( \ 365 Z_DO_LOG_MODULE_REGISTER(__VA_ARGS__), \ 366 (_LOG_MODULE_DATA_CREATE(GET_ARG_N(1, __VA_ARGS__), \ 367 _LOG_LEVEL_RESOLVE(__VA_ARGS__))),\ 368 () \ 369 ) \ 370 LOG_MODULE_DECLARE(__VA_ARGS__) 371 372 /** 373 * @brief Macro for declaring a log module (not registering it). 374 * 375 * Modules which are split up over multiple files must have exactly 376 * one file use LOG_MODULE_REGISTER() to create module-specific state 377 * and register the module with the logger core. 378 * 379 * The other files in the module should use this macro instead to 380 * declare that same state. (Otherwise, LOG_INF() etc. will not be 381 * able to refer to module-specific state variables.) 382 * 383 * Macro accepts one or two parameters: 384 * - module name 385 * - optional log level. If not provided then default log level is used in 386 * the file. 387 * 388 * Example usage: 389 * - LOG_MODULE_DECLARE(foo, CONFIG_FOO_LOG_LEVEL) 390 * - LOG_MODULE_DECLARE(foo) 391 * 392 * @note The module's state is declared only if LOG_LEVEL for the 393 * current source file is non-zero or it is not defined and 394 * CONFIG_LOG_DEFAULT_LEVEL is non-zero. In other cases, 395 * this macro has no effect. 396 * @see LOG_MODULE_REGISTER 397 */ 398 #define LOG_MODULE_DECLARE(...) \ 399 extern const struct log_source_const_data \ 400 Z_LOG_ITEM_CONST_DATA(GET_ARG_N(1, __VA_ARGS__)); \ 401 extern struct log_source_dynamic_data \ 402 LOG_ITEM_DYNAMIC_DATA(GET_ARG_N(1, __VA_ARGS__)); \ 403 \ 404 static const struct log_source_const_data * \ 405 __log_current_const_data __unused = \ 406 Z_DO_LOG_MODULE_REGISTER(__VA_ARGS__) ? \ 407 &Z_LOG_ITEM_CONST_DATA(GET_ARG_N(1, __VA_ARGS__)) : \ 408 NULL; \ 409 \ 410 static struct log_source_dynamic_data * \ 411 __log_current_dynamic_data __unused = \ 412 (Z_DO_LOG_MODULE_REGISTER(__VA_ARGS__) && \ 413 IS_ENABLED(CONFIG_LOG_RUNTIME_FILTERING)) ? \ 414 &LOG_ITEM_DYNAMIC_DATA(GET_ARG_N(1, __VA_ARGS__)) : \ 415 NULL; \ 416 \ 417 static const uint32_t __log_level __unused = \ 418 _LOG_LEVEL_RESOLVE(__VA_ARGS__) 419 420 /** 421 * @brief Macro for setting log level in the file or function where instance 422 * logging API is used. 423 * 424 * @param level Level used in file or in function. 425 * 426 */ 427 #define LOG_LEVEL_SET(level) static const uint32_t __log_level __unused = \ 428 Z_LOG_RESOLVED_LEVEL(level, 0) 429 430 #ifdef CONFIG_LOG_CUSTOM_HEADER 431 /* This include must always be at the end of log.h */ 432 #include <zephyr_custom_log.h> 433 #endif 434 435 /* 436 * Eclipse CDT or JetBrains Clion parser is sometimes confused by logging API 437 * code and freezes the whole IDE. Following lines hides LOG_x macros from them. 438 */ 439 #if defined(__CDT_PARSER__) || defined(__JETBRAINS_IDE__) 440 #undef LOG_ERR 441 #undef LOG_WRN 442 #undef LOG_INF 443 #undef LOG_DBG 444 445 #undef LOG_HEXDUMP_ERR 446 #undef LOG_HEXDUMP_WRN 447 #undef LOG_HEXDUMP_INF 448 #undef LOG_HEXDUMP_DBG 449 450 #define LOG_ERR(...) (void) 0 451 #define LOG_WRN(...) (void) 0 452 #define LOG_DBG(...) (void) 0 453 #define LOG_INF(...) (void) 0 454 455 #define LOG_HEXDUMP_ERR(...) (void) 0 456 #define LOG_HEXDUMP_WRN(...) (void) 0 457 #define LOG_HEXDUMP_DBG(...) (void) 0 458 #define LOG_HEXDUMP_INF(...) (void) 0 459 #endif 460 461 /** 462 * @} 463 */ 464 465 #endif /* ZEPHYR_INCLUDE_LOGGING_LOG_H_ */ 466
