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