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(COND_CODE_0(LOG_LEVEL, (1), (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(CONFIG_LOG_FMT_SECTION, ( \ 303 static const char UTIL_CAT(_name, _str)[] \ 304 __in_section(_log_strings, static, _CONCAT(_name, _)) __used __noasan = \ 305 STRINGIFY(_name);)) \ 306 IF_ENABLED(LOG_IN_CPLUSPLUS, (extern)) \ 307 const STRUCT_SECTION_ITERABLE_ALTERNATE(log_const, \ 308 log_source_const_data, \ 309 Z_LOG_ITEM_CONST_DATA(_name)) = \ 310 { \ 311 .name = COND_CODE_1(CONFIG_LOG_FMT_SECTION, \ 312 (UTIL_CAT(_name, _str)), (STRINGIFY(_name))), \ 313 .level = _level \ 314 } 315 316 #define _LOG_MODULE_DYNAMIC_DATA_CREATE(_name) \ 317 STRUCT_SECTION_ITERABLE_ALTERNATE(log_dynamic, log_source_dynamic_data, \ 318 LOG_ITEM_DYNAMIC_DATA(_name)) 319 320 #define _LOG_MODULE_DYNAMIC_DATA_COND_CREATE(_name) \ 321 IF_ENABLED(CONFIG_LOG_RUNTIME_FILTERING, \ 322 (_LOG_MODULE_DYNAMIC_DATA_CREATE(_name);)) 323 324 #define _LOG_MODULE_DATA_CREATE(_name, _level) \ 325 _LOG_MODULE_CONST_DATA_CREATE(_name, _level); \ 326 _LOG_MODULE_DYNAMIC_DATA_COND_CREATE(_name) 327 328 /* Determine if data for the module shall be created. It is created if logging 329 * is enabled, override level is set or module specific level is set (not off). 330 */ 331 #define Z_DO_LOG_MODULE_REGISTER(...) \ 332 COND_CODE_1(CONFIG_LOG, \ 333 (Z_LOG_EVAL(CONFIG_LOG_OVERRIDE_LEVEL, \ 334 (1), \ 335 (Z_LOG_EVAL(_LOG_LEVEL_RESOLVE(__VA_ARGS__), (1), (0))) \ 336 )), (0)) 337 338 /** 339 * @brief Create module-specific state and register the module with Logger. 340 * 341 * This macro normally must be used after including <zephyr/logging/log.h> to 342 * complete the initialization of the module. 343 * 344 * Module registration can be skipped in two cases: 345 * 346 * - The module consists of more than one file, and another file 347 * invokes this macro. (LOG_MODULE_DECLARE() should be used instead 348 * in all of the module's other files.) 349 * - Instance logging is used and there is no need to create module entry. In 350 * that case LOG_LEVEL_SET() should be used to set log level used within the 351 * file. 352 * 353 * Macro accepts one or two parameters: 354 * - module name 355 * - optional log level. If not provided then default log level is used in 356 * the file. 357 * 358 * Example usage: 359 * - LOG_MODULE_REGISTER(foo, CONFIG_FOO_LOG_LEVEL) 360 * - LOG_MODULE_REGISTER(foo) 361 * 362 * 363 * @note The module's state is defined, and the module is registered, 364 * only if LOG_LEVEL for the current source file is non-zero or 365 * it is not defined and CONFIG_LOG_DEFAULT_LEVEL is non-zero. 366 * In other cases, this macro has no effect. 367 * @see LOG_MODULE_DECLARE 368 */ 369 #define LOG_MODULE_REGISTER(...) \ 370 COND_CODE_1( \ 371 Z_DO_LOG_MODULE_REGISTER(__VA_ARGS__), \ 372 (_LOG_MODULE_DATA_CREATE(GET_ARG_N(1, __VA_ARGS__), \ 373 _LOG_LEVEL_RESOLVE(__VA_ARGS__))),\ 374 () \ 375 ) \ 376 LOG_MODULE_DECLARE(__VA_ARGS__) 377 378 /** 379 * @brief Macro for declaring a log module (not registering it). 380 * 381 * Modules which are split up over multiple files must have exactly 382 * one file use LOG_MODULE_REGISTER() to create module-specific state 383 * and register the module with the logger core. 384 * 385 * The other files in the module should use this macro instead to 386 * declare that same state. (Otherwise, LOG_INF() etc. will not be 387 * able to refer to module-specific state variables.) 388 * 389 * Macro accepts one or two parameters: 390 * - module name 391 * - optional log level. If not provided then default log level is used in 392 * the file. 393 * 394 * Example usage: 395 * - LOG_MODULE_DECLARE(foo, CONFIG_FOO_LOG_LEVEL) 396 * - LOG_MODULE_DECLARE(foo) 397 * 398 * @note The module's state is declared only if LOG_LEVEL for the 399 * current source file is non-zero or it is not defined and 400 * CONFIG_LOG_DEFAULT_LEVEL is non-zero. In other cases, 401 * this macro has no effect. 402 * @see LOG_MODULE_REGISTER 403 */ 404 #define LOG_MODULE_DECLARE(...) \ 405 extern const struct log_source_const_data \ 406 Z_LOG_ITEM_CONST_DATA(GET_ARG_N(1, __VA_ARGS__)); \ 407 extern struct log_source_dynamic_data \ 408 LOG_ITEM_DYNAMIC_DATA(GET_ARG_N(1, __VA_ARGS__)); \ 409 \ 410 static const struct log_source_const_data * \ 411 __log_current_const_data __unused = \ 412 Z_DO_LOG_MODULE_REGISTER(__VA_ARGS__) ? \ 413 &Z_LOG_ITEM_CONST_DATA(GET_ARG_N(1, __VA_ARGS__)) : \ 414 NULL; \ 415 \ 416 static struct log_source_dynamic_data * \ 417 __log_current_dynamic_data __unused = \ 418 (Z_DO_LOG_MODULE_REGISTER(__VA_ARGS__) && \ 419 IS_ENABLED(CONFIG_LOG_RUNTIME_FILTERING)) ? \ 420 &LOG_ITEM_DYNAMIC_DATA(GET_ARG_N(1, __VA_ARGS__)) : \ 421 NULL; \ 422 \ 423 static const uint32_t __log_level __unused = \ 424 _LOG_LEVEL_RESOLVE(__VA_ARGS__) 425 426 /** 427 * @brief Macro for setting log level in the file or function where instance 428 * logging API is used. 429 * 430 * @param level Level used in file or in function. 431 * 432 */ 433 #define LOG_LEVEL_SET(level) static const uint32_t __log_level __unused = \ 434 Z_LOG_RESOLVED_LEVEL(level, 0) 435 436 #ifdef CONFIG_LOG_CUSTOM_HEADER 437 /* This include must always be at the end of log.h */ 438 #include <zephyr_custom_log.h> 439 #endif 440 441 /* 442 * Eclipse CDT or JetBrains Clion parser is sometimes confused by logging API 443 * code and freezes the whole IDE. Following lines hides LOG_x macros from them. 444 */ 445 #if defined(__CDT_PARSER__) || defined(__JETBRAINS_IDE__) 446 #undef LOG_ERR 447 #undef LOG_WRN 448 #undef LOG_INF 449 #undef LOG_DBG 450 451 #undef LOG_HEXDUMP_ERR 452 #undef LOG_HEXDUMP_WRN 453 #undef LOG_HEXDUMP_INF 454 #undef LOG_HEXDUMP_DBG 455 456 #define LOG_ERR(...) (void) 0 457 #define LOG_WRN(...) (void) 0 458 #define LOG_DBG(...) (void) 0 459 #define LOG_INF(...) (void) 0 460 461 #define LOG_HEXDUMP_ERR(...) (void) 0 462 #define LOG_HEXDUMP_WRN(...) (void) 0 463 #define LOG_HEXDUMP_DBG(...) (void) 0 464 #define LOG_HEXDUMP_INF(...) (void) 0 465 #endif 466 467 /** 468 * @} 469 */ 470 471 #endif /* ZEPHYR_INCLUDE_LOGGING_LOG_H_ */ 472
