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 : #include <zephyr/sys/atomic.h>
14 : #include <zephyr/sys/util_macro.h>
15 :
16 : #if CONFIG_USERSPACE && CONFIG_LOG_ALWAYS_RUNTIME
17 : #include <zephyr/app_memory/app_memdomain.h>
18 : #endif
19 :
20 : #ifdef CONFIG_LOG_RATELIMIT
21 : #include <zephyr/kernel.h>
22 : #endif
23 :
24 : #ifdef __cplusplus
25 : extern "C" {
26 : #endif
27 :
28 : #ifdef CONFIG_LOG_RATELIMIT
29 : #define LOG_RATELIMIT_INTERVAL_MS CONFIG_LOG_RATELIMIT_INTERVAL_MS
30 :
31 : #else
32 0 : #define LOG_RATELIMIT_INTERVAL_MS 0
33 :
34 : #endif
35 :
36 : /**
37 : * @brief Logging
38 : * @defgroup logging Logging
39 : * @since 1.13
40 : * @version 1.0.0
41 : * @ingroup os_services
42 : * @{
43 : * @}
44 : */
45 :
46 : /**
47 : * @brief Logger API
48 : * @defgroup log_api Logging API
49 : * @ingroup logger
50 : * @{
51 : */
52 :
53 : /**
54 : * @brief Writes an ERROR level message to the log.
55 : *
56 : * @details It's meant to report severe errors, such as those from which it's
57 : * not possible to recover.
58 : *
59 : * @param ... A string optionally containing printk valid conversion specifier,
60 : * followed by as many values as specifiers.
61 : */
62 1 : #define LOG_ERR(...) Z_LOG(LOG_LEVEL_ERR, __VA_ARGS__)
63 :
64 : /**
65 : * @brief Writes a WARNING level message to the log.
66 : *
67 : * @details It's meant to register messages related to unusual situations that
68 : * are not necessarily errors.
69 : *
70 : * @param ... A string optionally containing printk valid conversion specifier,
71 : * followed by as many values as specifiers.
72 : */
73 1 : #define LOG_WRN(...) Z_LOG(LOG_LEVEL_WRN, __VA_ARGS__)
74 :
75 : /**
76 : * @brief Writes an INFO level message to the log.
77 : *
78 : * @details It's meant to write generic user oriented messages.
79 : *
80 : * @param ... A string optionally containing printk valid conversion specifier,
81 : * followed by as many values as specifiers.
82 : */
83 1 : #define LOG_INF(...) Z_LOG(LOG_LEVEL_INF, __VA_ARGS__)
84 :
85 : /**
86 : * @brief Writes a DEBUG level message to the log.
87 : *
88 : * @details It's meant to write developer oriented information.
89 : *
90 : * @param ... A string optionally containing printk valid conversion specifier,
91 : * followed by as many values as specifiers.
92 : */
93 1 : #define LOG_DBG(...) Z_LOG(LOG_LEVEL_DBG, __VA_ARGS__)
94 :
95 : /**
96 : * @brief Writes a WARNING level message to the log on the first execution only.
97 : *
98 : * @details It's meant for situations that warrant investigation but could clutter
99 : * the logs if output on every execution.
100 : *
101 : * @param ... A string optionally containing printk valid conversion specifier,
102 : * followed by as many values as specifiers.
103 : */
104 1 : #define LOG_WRN_ONCE(...) \
105 : do { \
106 : static atomic_t __warned; \
107 : if (unlikely(atomic_cas(&__warned, 0, 1))) { \
108 : Z_LOG(LOG_LEVEL_WRN, __VA_ARGS__); \
109 : } \
110 : } while (0)
111 :
112 : /**
113 : * @brief Core rate-limited logging macro for regular messages
114 : *
115 : * @details Internal macro that provides rate-limited logging functionality
116 : * for regular log messages. Uses atomic operations to ensure thread safety
117 : * in multi-threaded environments. Only one thread can successfully log a
118 : * message within the specified rate limit period.
119 : *
120 : * @param _level Log level (LOG_LEVEL_ERR, LOG_LEVEL_WRN, etc.)
121 : * @param _rate_ms Minimum interval in milliseconds between log messages.
122 : * @param ... Arguments to pass to the logging function.
123 : */
124 : #define _LOG_RATELIMIT_CORE(_level, _rate_ms, ...) \
125 : do { \
126 : static atomic_t __last_log_time; \
127 : static atomic_t __skipped_count; \
128 : uint32_t __now = k_uptime_get_32(); \
129 : uint32_t __last = atomic_get(&__last_log_time); \
130 : uint32_t __diff = __now - __last; \
131 : if (unlikely(__diff >= (_rate_ms))) { \
132 : if (atomic_cas(&__last_log_time, __last, __now)) { \
133 : uint32_t __skipped = atomic_clear(&__skipped_count); \
134 : if (__skipped > 0) { \
135 : Z_LOG(_level, "Skipped %d messages", __skipped); \
136 : } \
137 : Z_LOG(_level, __VA_ARGS__); \
138 : } else { \
139 : atomic_inc(&__skipped_count); \
140 : } \
141 : } else { \
142 : atomic_inc(&__skipped_count); \
143 : } \
144 : } while (0)
145 :
146 : /**
147 : * @brief Rate-limited logging macros
148 : *
149 : * @details These macros provide rate-limited logging functionality to prevent
150 : * log flooding when messages are generated frequently. Each macro ensures that
151 : * log messages are not output more frequently than a specified interval.
152 : * Rate limiting is per-macro-call-site, meaning each unique call has its own
153 : * independent rate limit.
154 : *
155 : * The macros use atomic operations to ensure thread safety in multi-threaded
156 : * environments. Only one thread can successfully log a message within the
157 : * specified rate limit period.
158 : *
159 : * @see CONFIG_LOG_RATELIMIT_INTERVAL_MS
160 : */
161 :
162 : /**
163 : * @brief Core rate-limited logging macro with level parameter
164 : *
165 : * @details Internal macro that provides rate-limited logging functionality
166 : * with configurable log level. Uses atomic operations to ensure thread safety
167 : * in multi-threaded environments.
168 : *
169 : * @param _level Log level (LOG_LEVEL_ERR, LOG_LEVEL_WRN, etc.)
170 : * @param _rate_ms Minimum interval in milliseconds between log messages.
171 : * @param ... Arguments to pass to the logging function.
172 : */
173 : #define _LOG_RATELIMIT_LVL(_level, _rate_ms, ...) \
174 : do { \
175 : if (IS_ENABLED(CONFIG_LOG_RATELIMIT)) { \
176 : _LOG_RATELIMIT_CORE(_level, _rate_ms, __VA_ARGS__); \
177 : } else if (IS_ENABLED(CONFIG_LOG_RATELIMIT_FALLBACK_DROP)) { \
178 : (void)0; \
179 : } else { \
180 : Z_LOG(_level, __VA_ARGS__); \
181 : } \
182 : } while (0)
183 :
184 : /**
185 : * @brief Writes a WARNING level message to the log with rate limiting.
186 : *
187 : * @details It's meant for situations that warrant investigation but could clutter
188 : * the logs if output too frequently. The message will be logged at most once
189 : * per default interval (see CONFIG_LOG_RATELIMIT_INTERVAL_MS).
190 : *
191 : * @param ... A string optionally containing printk valid conversion specifier,
192 : * followed by as many values as specifiers.
193 : */
194 1 : #define LOG_WRN_RATELIMIT(...) \
195 : _LOG_RATELIMIT_LVL(LOG_LEVEL_WRN, LOG_RATELIMIT_INTERVAL_MS, __VA_ARGS__)
196 :
197 : /**
198 : * @brief Writes an ERROR level message to the log with rate limiting.
199 : *
200 : * @details It's meant to report severe errors, such as those from which it's
201 : * not possible to recover, but with rate limiting to prevent log flooding.
202 : * The message will be logged at most once per default interval (see
203 : * CONFIG_LOG_RATELIMIT_INTERVAL_MS).
204 : *
205 : * @param ... A string optionally containing printk valid conversion specifier,
206 : * followed by as many values as specifiers.
207 : */
208 1 : #define LOG_ERR_RATELIMIT(...) \
209 : _LOG_RATELIMIT_LVL(LOG_LEVEL_ERR, LOG_RATELIMIT_INTERVAL_MS, __VA_ARGS__)
210 :
211 : /**
212 : * @brief Writes an INFO level message to the log with rate limiting.
213 : *
214 : * @details It's meant to write generic user oriented messages with rate limiting
215 : * to prevent log flooding. The message will be logged at most once per default
216 : * interval (see CONFIG_LOG_RATELIMIT_INTERVAL_MS).
217 : *
218 : * @param ... A string optionally containing printk valid conversion specifier,
219 : * followed by as many values as specifiers.
220 : */
221 1 : #define LOG_INF_RATELIMIT(...) \
222 : _LOG_RATELIMIT_LVL(LOG_LEVEL_INF, LOG_RATELIMIT_INTERVAL_MS, __VA_ARGS__)
223 :
224 : /**
225 : * @brief Writes a DEBUG level message to the log with rate limiting.
226 : *
227 : * @details It's meant to write developer oriented information with rate limiting
228 : * to prevent log flooding. The message will be logged at most once per default
229 : * interval (see CONFIG_LOG_RATELIMIT_INTERVAL_MS).
230 : *
231 : * @param ... A string optionally containing printk valid conversion specifier,
232 : * followed by as many values as specifiers.
233 : */
234 1 : #define LOG_DBG_RATELIMIT(...) \
235 : _LOG_RATELIMIT_LVL(LOG_LEVEL_DBG, LOG_RATELIMIT_INTERVAL_MS, __VA_ARGS__)
236 :
237 : /**
238 : * @brief Core rate-limited logging macro for hexdump messages
239 : *
240 : * @details Internal macro that provides rate-limited logging functionality
241 : * for hexdump log messages. Uses atomic operations to ensure thread safety
242 : * in multi-threaded environments. Only one thread can successfully log a
243 : * message within the specified rate limit period.
244 : *
245 : * @param _level Log level (LOG_LEVEL_ERR, LOG_LEVEL_WRN, etc.)
246 : * @param _rate_ms Minimum interval in milliseconds between log messages.
247 : * @param _data Pointer to the data to be logged.
248 : * @param _length Length of data (in bytes).
249 : * @param _str Persistent, raw string.
250 : */
251 : #define _LOG_HEXDUMP_RATELIMIT_CORE(_level, _rate_ms, _data, _length, _str) \
252 : do { \
253 : static atomic_t __last_log_time; \
254 : static atomic_t __skipped_count; \
255 : uint32_t __now = k_uptime_get_32(); \
256 : uint32_t __last = atomic_get(&__last_log_time); \
257 : uint32_t __diff = __now - __last; \
258 : if (unlikely(__diff >= (_rate_ms))) { \
259 : if (atomic_cas(&__last_log_time, __last, __now)) { \
260 : uint32_t __skipped = atomic_clear(&__skipped_count); \
261 : if (__skipped > 0) { \
262 : Z_LOG(_level, "Skipped %d hexdump messages", __skipped); \
263 : } \
264 : Z_LOG_HEXDUMP(_level, _data, _length, _str); \
265 : } else { \
266 : atomic_inc(&__skipped_count); \
267 : } \
268 : } else { \
269 : atomic_inc(&__skipped_count); \
270 : } \
271 : } while (0)
272 :
273 : /**
274 : * @brief Core rate-limited hexdump logging macro with level parameter
275 : *
276 : * @details Internal macro that provides rate-limited hexdump logging functionality
277 : * with configurable log level. Uses atomic operations to ensure thread safety
278 : * in multi-threaded environments.
279 : *
280 : * @param _level Log level (LOG_LEVEL_ERR, LOG_LEVEL_WRN, etc.)
281 : * @param _rate_ms Minimum interval in milliseconds between log messages.
282 : * @param _data Pointer to the data to be logged.
283 : * @param _length Length of data (in bytes).
284 : * @param _str Persistent, raw string.
285 : */
286 : #define _LOG_HEXDUMP_RATELIMIT_LVL(_level, _rate_ms, _data, _length, _str) \
287 : do { \
288 : if (IS_ENABLED(CONFIG_LOG_RATELIMIT)) { \
289 : _LOG_HEXDUMP_RATELIMIT_CORE(_level, _rate_ms, _data, _length, _str); \
290 : } else if (IS_ENABLED(CONFIG_LOG_RATELIMIT_FALLBACK_DROP)) { \
291 : (void)0; \
292 : } else { \
293 : Z_LOG_HEXDUMP(_level, _data, _length, _str); \
294 : } \
295 : } while (0)
296 :
297 : /**
298 : * @brief Writes an ERROR level hexdump message to the log with rate limiting.
299 : *
300 : * @details It's meant to report severe errors, such as those from which it's
301 : * not possible to recover, but with rate limiting to prevent log flooding.
302 : * The message will be logged at most once per default interval (see
303 : * CONFIG_LOG_RATELIMIT_INTERVAL_MS).
304 : *
305 : * @param _data Pointer to the data to be logged.
306 : * @param _length Length of data (in bytes).
307 : * @param _str Persistent, raw string.
308 : */
309 1 : #define LOG_HEXDUMP_ERR_RATELIMIT(_data, _length, _str) \
310 : _LOG_HEXDUMP_RATELIMIT_LVL(LOG_LEVEL_ERR, LOG_RATELIMIT_INTERVAL_MS, _data, _length, _str)
311 :
312 : /**
313 : * @brief Writes a WARNING level hexdump message to the log with rate limiting.
314 : *
315 : * @details It's meant to register messages related to unusual situations that
316 : * are not necessarily errors, but with rate limiting to prevent log flooding.
317 : * The message will be logged at most once per default interval (see
318 : * CONFIG_LOG_RATELIMIT_INTERVAL_MS).
319 : *
320 : * @param _data Pointer to the data to be logged.
321 : * @param _length Length of data (in bytes).
322 : * @param _str Persistent, raw string.
323 : */
324 1 : #define LOG_HEXDUMP_WRN_RATELIMIT(_data, _length, _str) \
325 : _LOG_HEXDUMP_RATELIMIT_LVL(LOG_LEVEL_WRN, LOG_RATELIMIT_INTERVAL_MS, _data, _length, _str)
326 :
327 : /**
328 : * @brief Writes an INFO level hexdump message to the log with rate limiting.
329 : *
330 : * @details It's meant to write generic user oriented messages with rate limiting
331 : * to prevent log flooding. The message will be logged at most once per default
332 : * interval (see CONFIG_LOG_RATELIMIT_INTERVAL_MS).
333 : *
334 : * @param _data Pointer to the data to be logged.
335 : * @param _length Length of data (in bytes).
336 : * @param _str Persistent, raw string.
337 : */
338 1 : #define LOG_HEXDUMP_INF_RATELIMIT(_data, _length, _str) \
339 : _LOG_HEXDUMP_RATELIMIT_LVL(LOG_LEVEL_INF, LOG_RATELIMIT_INTERVAL_MS, _data, _length, _str)
340 :
341 : /**
342 : * @brief Writes a DEBUG level hexdump message to the log with rate limiting.
343 : *
344 : * @details It's meant to write developer oriented information with rate limiting
345 : * to prevent log flooding. The message will be logged at most once per default
346 : * interval (see CONFIG_LOG_RATELIMIT_INTERVAL_MS).
347 : *
348 : * @param _data Pointer to the data to be logged.
349 : * @param _length Length of data (in bytes).
350 : * @param _str Persistent, raw string.
351 : */
352 1 : #define LOG_HEXDUMP_DBG_RATELIMIT(_data, _length, _str) \
353 : _LOG_HEXDUMP_RATELIMIT_LVL(LOG_LEVEL_DBG, LOG_RATELIMIT_INTERVAL_MS, _data, _length, _str)
354 :
355 : /**
356 : * @brief Rate-limited logging macros with custom rate
357 : *
358 : * @details These macros provide rate-limited logging functionality with custom
359 : * rate intervals. They take an explicit rate parameter (in milliseconds) that
360 : * specifies the minimum interval between log messages.
361 : */
362 :
363 : /**
364 : * @brief Writes an ERROR level message to the log with custom rate limiting.
365 : *
366 : * @details It's meant to report severe errors, such as those from which it's
367 : * not possible to recover, but with rate limiting to prevent log flooding.
368 : * The message will be logged at most once per specified interval.
369 : *
370 : * @param _rate_ms Minimum interval in milliseconds between log messages.
371 : * @param ... A string optionally containing printk valid conversion specifier,
372 : * followed by as many values as specifiers.
373 : */
374 1 : #define LOG_ERR_RATELIMIT_RATE(_rate_ms, ...) \
375 : _LOG_RATELIMIT_LVL(LOG_LEVEL_ERR, _rate_ms, __VA_ARGS__)
376 :
377 : /**
378 : * @brief Writes a WARNING level message to the log with custom rate limiting.
379 : *
380 : * @details It's meant for situations that warrant investigation but could clutter
381 : * the logs if output too frequently. The message will be logged at most once
382 : * per specified interval.
383 : *
384 : * @param _rate_ms Minimum interval in milliseconds between log messages.
385 : * @param ... A string optionally containing printk valid conversion specifier,
386 : * followed by as many values as specifiers.
387 : */
388 1 : #define LOG_WRN_RATELIMIT_RATE(_rate_ms, ...) \
389 : _LOG_RATELIMIT_LVL(LOG_LEVEL_WRN, _rate_ms, __VA_ARGS__)
390 :
391 : /**
392 : * @brief Writes an INFO level message to the log with custom rate limiting.
393 : *
394 : * @details It's meant to write generic user oriented messages with rate limiting
395 : * to prevent log flooding. The message will be logged at most once per specified
396 : * interval.
397 : *
398 : * @param _rate_ms Minimum interval in milliseconds between log messages.
399 : * @param ... A string optionally containing printk valid conversion specifier,
400 : * followed by as many values as specifiers.
401 : */
402 1 : #define LOG_INF_RATELIMIT_RATE(_rate_ms, ...) \
403 : _LOG_RATELIMIT_LVL(LOG_LEVEL_INF, _rate_ms, __VA_ARGS__)
404 :
405 : /**
406 : * @brief Writes a DEBUG level message to the log with custom rate limiting.
407 : *
408 : * @details It's meant to write developer oriented information with rate limiting
409 : * to prevent log flooding. The message will be logged at most once per specified
410 : * interval.
411 : *
412 : * @param _rate_ms Minimum interval in milliseconds between log messages.
413 : * @param ... A string optionally containing printk valid conversion specifier,
414 : * followed by as many values as specifiers.
415 : */
416 1 : #define LOG_DBG_RATELIMIT_RATE(_rate_ms, ...) \
417 : _LOG_RATELIMIT_LVL(LOG_LEVEL_DBG, _rate_ms, __VA_ARGS__)
418 :
419 : /**
420 : * @brief Writes an ERROR level hexdump message to the log with custom rate limiting.
421 : *
422 : * @details It's meant to report severe errors, such as those from which it's
423 : * not possible to recover, but with rate limiting to prevent log flooding.
424 : * The message will be logged at most once per specified interval.
425 : *
426 : * @param _rate_ms Minimum interval in milliseconds between log messages.
427 : * @param _data Pointer to the data to be logged.
428 : * @param _length Length of data (in bytes).
429 : * @param _str Persistent, raw string.
430 : */
431 1 : #define LOG_HEXDUMP_ERR_RATELIMIT_RATE(_rate_ms, _data, _length, _str) \
432 : _LOG_HEXDUMP_RATELIMIT_LVL(LOG_LEVEL_ERR, _rate_ms, _data, _length, _str)
433 :
434 : /**
435 : * @brief Writes a WARNING level hexdump message to the log with custom rate limiting.
436 : *
437 : * @details It's meant to register messages related to unusual situations that
438 : * are not necessarily errors, but with rate limiting to prevent log flooding.
439 : * The message will be logged at most once per specified interval.
440 : *
441 : * @param _rate_ms Minimum interval in milliseconds between log messages.
442 : * @param _data Pointer to the data to be logged.
443 : * @param _length Length of data (in bytes).
444 : * @param _str Persistent, raw string.
445 : */
446 1 : #define LOG_HEXDUMP_WRN_RATELIMIT_RATE(_rate_ms, _data, _length, _str) \
447 : _LOG_HEXDUMP_RATELIMIT_LVL(LOG_LEVEL_WRN, _rate_ms, _data, _length, _str)
448 :
449 : /**
450 : * @brief Writes an INFO level hexdump message to the log with custom rate limiting.
451 : *
452 : * @details It's meant to write generic user oriented messages with rate limiting
453 : * to prevent log flooding. The message will be logged at most once per specified
454 : * interval.
455 : *
456 : * @param _rate_ms Minimum interval in milliseconds between log messages.
457 : * @param _data Pointer to the data to be logged.
458 : * @param _length Length of data (in bytes).
459 : * @param _str Persistent, raw string.
460 : */
461 1 : #define LOG_HEXDUMP_INF_RATELIMIT_RATE(_rate_ms, _data, _length, _str) \
462 : _LOG_HEXDUMP_RATELIMIT_LVL(LOG_LEVEL_INF, _rate_ms, _data, _length, _str)
463 :
464 : /**
465 : * @brief Writes a DEBUG level hexdump message to the log with custom rate limiting.
466 : *
467 : * @details It's meant to write developer oriented information with rate limiting
468 : * to prevent log flooding. The message will be logged at most once per specified
469 : * interval.
470 : *
471 : * @param _rate_ms Minimum interval in milliseconds between log messages.
472 : * @param _data Pointer to the data to be logged.
473 : * @param _length Length of data (in bytes).
474 : * @param _str Persistent, raw string.
475 : */
476 1 : #define LOG_HEXDUMP_DBG_RATELIMIT_RATE(_rate_ms, _data, _length, _str) \
477 : _LOG_HEXDUMP_RATELIMIT_LVL(LOG_LEVEL_DBG, _rate_ms, _data, _length, _str)
478 :
479 : /**
480 : * @brief Unconditionally print raw log message.
481 : *
482 : * The result is same as if printk was used but it goes through logging
483 : * infrastructure thus utilizes logging mode, e.g. deferred mode.
484 : *
485 : * @param ... A string optionally containing printk valid conversion specifier,
486 : * followed by as many values as specifiers.
487 : */
488 1 : #define LOG_PRINTK(...) Z_LOG_PRINTK(0, __VA_ARGS__)
489 :
490 : /**
491 : * @brief Unconditionally print raw log message.
492 : *
493 : * Provided string is printed as is without appending any characters (e.g., color or newline).
494 : *
495 : * @param ... A string optionally containing printk valid conversion specifier,
496 : * followed by as many values as specifiers.
497 : */
498 1 : #define LOG_RAW(...) Z_LOG_PRINTK(1, __VA_ARGS__)
499 :
500 : /**
501 : * @brief Writes an ERROR level message associated with the instance to the log.
502 : *
503 : * Message is associated with specific instance of the module which has
504 : * independent filtering settings (if runtime filtering is enabled) and
505 : * message prefix (\<module_name\>.\<instance_name\>). It's meant to report
506 : * severe errors, such as those from which it's not possible to recover.
507 : *
508 : * @param _log_inst Pointer to the log structure associated with the instance.
509 : * @param ... A string optionally containing printk valid conversion specifier,
510 : * followed by as many values as specifiers.
511 : */
512 1 : #define LOG_INST_ERR(_log_inst, ...) Z_LOG_INSTANCE(LOG_LEVEL_ERR, _log_inst, __VA_ARGS__)
513 :
514 : /**
515 : * @brief Writes a WARNING level message associated with the instance to the
516 : * log.
517 : *
518 : * Message is associated with specific instance of the module which has
519 : * independent filtering settings (if runtime filtering is enabled) and
520 : * message prefix (\<module_name\>.\<instance_name\>). It's meant to register
521 : * messages related to unusual situations that are not necessarily errors.
522 : *
523 : * @param _log_inst Pointer to the log structure associated with the instance.
524 : * @param ... A string optionally containing printk valid conversion
525 : * specifier, followed by as many values as specifiers.
526 : */
527 1 : #define LOG_INST_WRN(_log_inst, ...) Z_LOG_INSTANCE(LOG_LEVEL_WRN, _log_inst, __VA_ARGS__)
528 :
529 : /**
530 : * @brief Writes an INFO level message associated with the instance to the log.
531 : *
532 : * Message is associated with specific instance of the module which has
533 : * independent filtering settings (if runtime filtering is enabled) and
534 : * message prefix (\<module_name\>.\<instance_name\>). It's meant to write
535 : * generic user oriented messages.
536 : *
537 : * @param _log_inst Pointer to the log structure associated with the instance.
538 : * @param ... A string optionally containing printk valid conversion specifier,
539 : * followed by as many values as specifiers.
540 : */
541 1 : #define LOG_INST_INF(_log_inst, ...) Z_LOG_INSTANCE(LOG_LEVEL_INF, _log_inst, __VA_ARGS__)
542 :
543 : /**
544 : * @brief Writes a DEBUG level message associated with the instance to the log.
545 : *
546 : * Message is associated with specific instance of the module which has
547 : * independent filtering settings (if runtime filtering is enabled) and
548 : * message prefix (\<module_name\>.\<instance_name\>). It's meant to write
549 : * developer oriented information.
550 : *
551 : * @param _log_inst Pointer to the log structure associated with the instance.
552 : * @param ... A string optionally containing printk valid conversion specifier,
553 : * followed by as many values as specifiers.
554 : */
555 1 : #define LOG_INST_DBG(_log_inst, ...) Z_LOG_INSTANCE(LOG_LEVEL_DBG, _log_inst, __VA_ARGS__)
556 :
557 : /**
558 : * @brief Writes an ERROR level hexdump message to the log.
559 : *
560 : * @details It's meant to report severe errors, such as those from which it's
561 : * not possible to recover.
562 : *
563 : * @param _data Pointer to the data to be logged.
564 : * @param _length Length of data (in bytes).
565 : * @param _str Persistent, raw string.
566 : */
567 1 : #define LOG_HEXDUMP_ERR(_data, _length, _str) Z_LOG_HEXDUMP(LOG_LEVEL_ERR, _data, _length, (_str))
568 :
569 : /**
570 : * @brief Writes a WARNING level message to the log.
571 : *
572 : * @details It's meant to register messages related to unusual situations that
573 : * are not necessarily errors.
574 : *
575 : * @param _data Pointer to the data to be logged.
576 : * @param _length Length of data (in bytes).
577 : * @param _str Persistent, raw string.
578 : */
579 1 : #define LOG_HEXDUMP_WRN(_data, _length, _str) Z_LOG_HEXDUMP(LOG_LEVEL_WRN, _data, _length, (_str))
580 :
581 : /**
582 : * @brief Writes an INFO level message to the log.
583 : *
584 : * @details It's meant to write generic user oriented messages.
585 : *
586 : * @param _data Pointer to the data to be logged.
587 : * @param _length Length of data (in bytes).
588 : * @param _str Persistent, raw string.
589 : */
590 1 : #define LOG_HEXDUMP_INF(_data, _length, _str) Z_LOG_HEXDUMP(LOG_LEVEL_INF, _data, _length, (_str))
591 :
592 : /**
593 : * @brief Writes a DEBUG level message to the log.
594 : *
595 : * @details It's meant to write developer oriented information.
596 : *
597 : * @param _data Pointer to the data to be logged.
598 : * @param _length Length of data (in bytes).
599 : * @param _str Persistent, raw string.
600 : */
601 1 : #define LOG_HEXDUMP_DBG(_data, _length, _str) Z_LOG_HEXDUMP(LOG_LEVEL_DBG, _data, _length, (_str))
602 :
603 : /**
604 : * @brief Writes an ERROR hexdump message associated with the instance to the
605 : * log.
606 : *
607 : * Message is associated with specific instance of the module which has
608 : * independent filtering settings (if runtime filtering is enabled) and
609 : * message prefix (\<module_name\>.\<instance_name\>). It's meant to report
610 : * severe errors, such as those from which it's not possible to recover.
611 : *
612 : * @param _log_inst Pointer to the log structure associated with the instance.
613 : * @param _data Pointer to the data to be logged.
614 : * @param _length Length of data (in bytes).
615 : * @param _str Persistent, raw string.
616 : */
617 1 : #define LOG_INST_HEXDUMP_ERR(_log_inst, _data, _length, _str) \
618 : Z_LOG_HEXDUMP_INSTANCE(LOG_LEVEL_ERR, _log_inst, _data, _length, _str)
619 :
620 : /**
621 : * @brief Writes a WARNING level hexdump message associated with the instance to
622 : * the log.
623 : *
624 : * @details It's meant to register messages related to unusual situations that
625 : * are not necessarily errors.
626 : *
627 : * @param _log_inst Pointer to the log structure associated with the instance.
628 : * @param _data Pointer to the data to be logged.
629 : * @param _length Length of data (in bytes).
630 : * @param _str Persistent, raw string.
631 : */
632 1 : #define LOG_INST_HEXDUMP_WRN(_log_inst, _data, _length, _str) \
633 : Z_LOG_HEXDUMP_INSTANCE(LOG_LEVEL_WRN, _log_inst, _data, _length, _str)
634 :
635 : /**
636 : * @brief Writes an INFO level hexdump message associated with the instance to
637 : * the log.
638 : *
639 : * @details It's meant to write generic user oriented messages.
640 : *
641 : * @param _log_inst Pointer to the log structure associated with the instance.
642 : * @param _data Pointer to the data to be logged.
643 : * @param _length Length of data (in bytes).
644 : * @param _str Persistent, raw string.
645 : */
646 1 : #define LOG_INST_HEXDUMP_INF(_log_inst, _data, _length, _str) \
647 : Z_LOG_HEXDUMP_INSTANCE(LOG_LEVEL_INF, _log_inst, _data, _length, _str)
648 :
649 : /**
650 : * @brief Writes a DEBUG level hexdump message associated with the instance to
651 : * the log.
652 : *
653 : * @details It's meant to write developer oriented information.
654 : *
655 : * @param _log_inst Pointer to the log structure associated with the instance.
656 : * @param _data Pointer to the data to be logged.
657 : * @param _length Length of data (in bytes).
658 : * @param _str Persistent, raw string.
659 : */
660 1 : #define LOG_INST_HEXDUMP_DBG(_log_inst, _data, _length, _str) \
661 : Z_LOG_HEXDUMP_INSTANCE(LOG_LEVEL_DBG, _log_inst, _data, _length, _str)
662 :
663 : /**
664 : * @brief Writes an formatted string to the log.
665 : *
666 : * @details Conditionally compiled (see CONFIG_LOG_PRINTK). Function provides
667 : * printk functionality.
668 : *
669 : * It is less efficient compared to standard logging because static packaging
670 : * cannot be used.
671 : *
672 : * @param fmt Formatted string to output.
673 : * @param ap Variable parameters.
674 : */
675 : void z_log_vprintk(const char *fmt, va_list ap);
676 :
677 : #ifdef __cplusplus
678 : }
679 : #define LOG_IN_CPLUSPLUS 1
680 : #endif
681 : /* Macro expects that optionally on second argument local log level is provided.
682 : * If provided it is returned, otherwise default log level is returned or
683 : * LOG_LEVEL, if it was locally defined.
684 : */
685 : #if !defined(CONFIG_LOG)
686 : #define _LOG_LEVEL_RESOLVE(...) LOG_LEVEL_NONE
687 : #else
688 : #define _LOG_LEVEL_RESOLVE(...) \
689 : Z_LOG_EVAL(COND_CODE_0(LOG_LEVEL, (1), (LOG_LEVEL)), \
690 : (GET_ARG_N(2, __VA_ARGS__, LOG_LEVEL)), \
691 : (GET_ARG_N(2, __VA_ARGS__, CONFIG_LOG_DEFAULT_LEVEL)))
692 : #endif
693 :
694 : /* Return first argument */
695 : #define _LOG_ARG1(arg1, ...) arg1
696 :
697 : #define _LOG_MODULE_CONST_DATA_CREATE(_name, _level) \
698 : IF_ENABLED(CONFIG_LOG_FMT_SECTION, ( \
699 : static const char UTIL_CAT(_name, _str)[] \
700 : __in_section(_log_strings, static, _CONCAT(_name, _)) __used __noasan = \
701 : STRINGIFY(_name);)) \
702 : IF_ENABLED(LOG_IN_CPLUSPLUS, (extern)) \
703 : const STRUCT_SECTION_ITERABLE_ALTERNATE(log_const, log_source_const_data, \
704 : Z_LOG_ITEM_CONST_DATA(_name)) = { \
705 : .name = COND_CODE_1(CONFIG_LOG_FMT_SECTION, \
706 : (UTIL_CAT(_name, _str)), (STRINGIFY(_name))), .level = (_level)}
707 :
708 : #define _LOG_MODULE_DYNAMIC_DATA_CREATE(_name) \
709 : STRUCT_SECTION_ITERABLE_ALTERNATE(log_dynamic, log_source_dynamic_data, \
710 : LOG_ITEM_DYNAMIC_DATA(_name))
711 :
712 : #define _LOG_MODULE_DYNAMIC_DATA_COND_CREATE(_name) \
713 : IF_ENABLED(CONFIG_LOG_RUNTIME_FILTERING, \
714 : (_LOG_MODULE_DYNAMIC_DATA_CREATE(_name);))
715 :
716 : #define _LOG_MODULE_DATA_CREATE(_name, _level) \
717 : _LOG_MODULE_CONST_DATA_CREATE(_name, _level); \
718 : _LOG_MODULE_DYNAMIC_DATA_COND_CREATE(_name)
719 :
720 : /* Determine if data for the module shall be created. It is created if logging
721 : * is enabled, override level is set or module specific level is set (not off).
722 : */
723 : #define Z_DO_LOG_MODULE_REGISTER(...) \
724 : COND_CODE_1(CONFIG_LOG, \
725 : (Z_LOG_EVAL(CONFIG_LOG_OVERRIDE_LEVEL, \
726 : (1), \
727 : (Z_LOG_EVAL(_LOG_LEVEL_RESOLVE(__VA_ARGS__), (1), (0))) \
728 : )), (0))
729 :
730 : /* Determine if the data of the log module shall be in the partition
731 : * 'k_log_partition' to allow a user mode thread access to this data.
732 : */
733 : #if CONFIG_USERSPACE && CONFIG_LOG_ALWAYS_RUNTIME
734 : extern struct k_mem_partition k_log_partition;
735 : #define Z_LOG_MODULE_PARTITION(_k_app_mem) _k_app_mem(k_log_partition)
736 : #else
737 : #define Z_LOG_MODULE_PARTITION(_k_app_mem)
738 : #endif
739 :
740 : /**
741 : * @brief Create module-specific state and register the module with Logger.
742 : *
743 : * This macro normally must be used after including <zephyr/logging/log.h> to
744 : * complete the initialization of the module.
745 : *
746 : * Module registration can be skipped in two cases:
747 : *
748 : * - The module consists of more than one file, and another file
749 : * invokes this macro. (LOG_MODULE_DECLARE() should be used instead
750 : * in all of the module's other files.)
751 : * - Instance logging is used and there is no need to create module entry. In
752 : * that case LOG_LEVEL_SET() should be used to set log level used within the
753 : * file.
754 : *
755 : * Macro accepts one or two parameters:
756 : * - module name
757 : * - optional log level. If not provided then default log level is used in
758 : * the file.
759 : *
760 : * Example usage:
761 : * - LOG_MODULE_REGISTER(foo, CONFIG_FOO_LOG_LEVEL)
762 : * - LOG_MODULE_REGISTER(foo)
763 : *
764 : *
765 : * @note The module's state is defined, and the module is registered,
766 : * only if LOG_LEVEL for the current source file is non-zero or
767 : * it is not defined and CONFIG_LOG_DEFAULT_LEVEL is non-zero.
768 : * In other cases, this macro has no effect.
769 : * @see LOG_MODULE_DECLARE
770 : */
771 1 : #define LOG_MODULE_REGISTER(...) \
772 : COND_CODE_1( \
773 : Z_DO_LOG_MODULE_REGISTER(__VA_ARGS__), \
774 : (_LOG_MODULE_DATA_CREATE(GET_ARG_N(1, __VA_ARGS__), \
775 : _LOG_LEVEL_RESOLVE(__VA_ARGS__))),\
776 : () \
777 : ) \
778 : LOG_MODULE_DECLARE(__VA_ARGS__)
779 :
780 : /**
781 : * @brief Macro for declaring a log module (not registering it).
782 : *
783 : * Modules which are split up over multiple files must have exactly
784 : * one file use LOG_MODULE_REGISTER() to create module-specific state
785 : * and register the module with the logger core.
786 : *
787 : * The other files in the module should use this macro instead to
788 : * declare that same state. (Otherwise, LOG_INF() etc. will not be
789 : * able to refer to module-specific state variables.)
790 : *
791 : * Macro accepts one or two parameters:
792 : * - module name
793 : * - optional log level. If not provided then default log level is used in
794 : * the file.
795 : *
796 : * Example usage:
797 : * - LOG_MODULE_DECLARE(foo, CONFIG_FOO_LOG_LEVEL)
798 : * - LOG_MODULE_DECLARE(foo)
799 : *
800 : * @note The module's state is declared only if LOG_LEVEL for the
801 : * current source file is non-zero or it is not defined and
802 : * CONFIG_LOG_DEFAULT_LEVEL is non-zero. In other cases,
803 : * this macro has no effect.
804 : * @see LOG_MODULE_REGISTER
805 : */
806 1 : #define LOG_MODULE_DECLARE(...) \
807 : extern const struct log_source_const_data Z_LOG_ITEM_CONST_DATA( \
808 : GET_ARG_N(1, __VA_ARGS__)); \
809 : extern struct log_source_dynamic_data LOG_ITEM_DYNAMIC_DATA(GET_ARG_N(1, __VA_ARGS__)); \
810 : \
811 : Z_LOG_MODULE_PARTITION(K_APP_DMEM) \
812 : static const struct log_source_const_data *__log_current_const_data __unused = \
813 : Z_DO_LOG_MODULE_REGISTER(__VA_ARGS__) \
814 : ? &Z_LOG_ITEM_CONST_DATA(GET_ARG_N(1, __VA_ARGS__)) \
815 : : NULL; \
816 : \
817 : Z_LOG_MODULE_PARTITION(K_APP_DMEM) \
818 : static struct log_source_dynamic_data *__log_current_dynamic_data __unused = \
819 : (Z_DO_LOG_MODULE_REGISTER(__VA_ARGS__) && \
820 : IS_ENABLED(CONFIG_LOG_RUNTIME_FILTERING)) \
821 : ? &LOG_ITEM_DYNAMIC_DATA(GET_ARG_N(1, __VA_ARGS__)) \
822 : : NULL; \
823 : \
824 : Z_LOG_MODULE_PARTITION(K_APP_BMEM) \
825 : static const uint32_t __log_level __unused = _LOG_LEVEL_RESOLVE(__VA_ARGS__)
826 :
827 : /**
828 : * @brief Macro for setting log level in the file or function where instance
829 : * logging API is used.
830 : *
831 : * @param level Level used in file or in function.
832 : *
833 : */
834 1 : #define LOG_LEVEL_SET(level) \
835 : static const uint32_t __log_level __unused = Z_LOG_RESOLVED_LEVEL(level, 0)
836 :
837 : #ifdef CONFIG_LOG_CUSTOM_HEADER
838 : /* This include must always be at the end of log.h */
839 : #include <zephyr_custom_log.h>
840 : #endif
841 :
842 : /*
843 : * Eclipse CDT or JetBrains Clion parser is sometimes confused by logging API
844 : * code and freezes the whole IDE. Following lines hides LOG_x macros from them.
845 : */
846 : #if defined(__CDT_PARSER__) || defined(__JETBRAINS_IDE__)
847 : #undef LOG_ERR
848 : #undef LOG_WRN
849 : #undef LOG_INF
850 : #undef LOG_DBG
851 :
852 : #undef LOG_HEXDUMP_ERR
853 : #undef LOG_HEXDUMP_WRN
854 : #undef LOG_HEXDUMP_INF
855 : #undef LOG_HEXDUMP_DBG
856 :
857 : #define LOG_ERR(...) (void)0
858 : #define LOG_WRN(...) (void)0
859 : #define LOG_DBG(...) (void)0
860 : #define LOG_INF(...) (void)0
861 :
862 : #define LOG_HEXDUMP_ERR(...) (void)0
863 : #define LOG_HEXDUMP_WRN(...) (void)0
864 : #define LOG_HEXDUMP_DBG(...) (void)0
865 : #define LOG_HEXDUMP_INF(...) (void)0
866 :
867 : #undef LOG_ERR_RATELIMIT
868 : #undef LOG_WRN_RATELIMIT
869 : #undef LOG_INF_RATELIMIT
870 : #undef LOG_DBG_RATELIMIT
871 :
872 : #undef LOG_ERR_RATELIMIT_RATE
873 : #undef LOG_WRN_RATELIMIT_RATE
874 : #undef LOG_INF_RATELIMIT_RATE
875 : #undef LOG_DBG_RATELIMIT_RATE
876 :
877 : #undef LOG_HEXDUMP_ERR_RATELIMIT
878 : #undef LOG_HEXDUMP_WRN_RATELIMIT
879 : #undef LOG_HEXDUMP_INF_RATELIMIT
880 : #undef LOG_HEXDUMP_DBG_RATELIMIT
881 :
882 : #undef LOG_HEXDUMP_ERR_RATELIMIT_RATE
883 : #undef LOG_HEXDUMP_WRN_RATELIMIT_RATE
884 : #undef LOG_HEXDUMP_INF_RATELIMIT_RATE
885 : #undef LOG_HEXDUMP_DBG_RATELIMIT_RATE
886 :
887 : #define LOG_ERR_RATELIMIT(...) (void)0
888 : #define LOG_WRN_RATELIMIT(...) (void)0
889 : #define LOG_INF_RATELIMIT(...) (void)0
890 : #define LOG_DBG_RATELIMIT(...) (void)0
891 :
892 : #define LOG_HEXDUMP_ERR_RATELIMIT(...) (void)0
893 : #define LOG_HEXDUMP_WRN_RATELIMIT(...) (void)0
894 : #define LOG_HEXDUMP_INF_RATELIMIT(...) (void)0
895 : #define LOG_HEXDUMP_DBG_RATELIMIT(...) (void)0
896 :
897 : #define LOG_ERR_RATELIMIT_RATE(...) (void)0
898 : #define LOG_WRN_RATELIMIT_RATE(...) (void)0
899 : #define LOG_INF_RATELIMIT_RATE(...) (void)0
900 : #define LOG_DBG_RATELIMIT_RATE(...) (void)0
901 :
902 : #define LOG_HEXDUMP_ERR_RATELIMIT_RATE(...) (void)0
903 : #define LOG_HEXDUMP_WRN_RATELIMIT_RATE(...) (void)0
904 : #define LOG_HEXDUMP_INF_RATELIMIT_RATE(...) (void)0
905 : #define LOG_HEXDUMP_DBG_RATELIMIT_RATE(...) (void)0
906 : #endif
907 :
908 : /**
909 : * @}
910 : */
911 :
912 : #endif /* ZEPHYR_INCLUDE_LOGGING_LOG_H_ */
|
