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