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