log: Add function to create a filter with flags
[J-u-boot.git] / include / log.h
CommitLineData
83d290c5 1/* SPDX-License-Identifier: GPL-2.0+ */
0e98b0a6
SG
2/*
3 * Logging support
4 *
5 * Copyright (c) 2017 Google, Inc
6 * Written by Simon Glass <sjg@chromium.org>
0e98b0a6
SG
7 */
8
9#ifndef __LOG_H
10#define __LOG_H
11
90526e9f 12#include <stdio.h>
09140113 13#include <linker_lists.h>
e9c8d49d 14#include <dm/uclass-id.h>
3c21d773 15#include <linux/bitops.h>
e9c8d49d
SG
16#include <linux/list.h>
17
09140113
SG
18struct cmd_tbl;
19
e9c8d49d
SG
20/** Log levels supported, ranging from most to least important */
21enum log_level_t {
6fc7e938 22 LOGL_EMERG = 0, /* U-Boot is unstable */
e9c8d49d
SG
23 LOGL_ALERT, /* Action must be taken immediately */
24 LOGL_CRIT, /* Critical conditions */
25 LOGL_ERR, /* Error that prevents something from working */
26 LOGL_WARNING, /* Warning may prevent optimial operation */
27 LOGL_NOTICE, /* Normal but significant condition, printf() */
28 LOGL_INFO, /* General information message */
29 LOGL_DEBUG, /* Basic debug-level message */
30 LOGL_DEBUG_CONTENT, /* Debug message showing full message content */
31 LOGL_DEBUG_IO, /* Debug message showing hardware I/O access */
32
33 LOGL_COUNT,
f941c8d7
SG
34 LOGL_NONE,
35
52d3df7f
SG
36 LOGL_LEVEL_MASK = 0xf, /* Mask for valid log levels */
37 LOGL_FORCE_DEBUG = 0x10, /* Mask to force output due to LOG_DEBUG */
38
e9c8d49d 39 LOGL_FIRST = LOGL_EMERG,
f941c8d7 40 LOGL_MAX = LOGL_DEBUG_IO,
d094a073 41 LOGL_CONT = -1, /* Use same log level as in previous call */
e9c8d49d
SG
42};
43
44/**
45 * Log categories supported. Most of these correspond to uclasses (i.e.
8021296a
SG
46 * enum uclass_id) but there are also some more generic categories.
47 *
48 * Remember to update log_cat_name[] after adding a new category.
e9c8d49d
SG
49 */
50enum log_category_t {
51 LOGC_FIRST = 0, /* First part mirrors UCLASS_... */
52
0bf96459
SG
53 LOGC_NONE = UCLASS_COUNT, /* First number is after all uclasses */
54 LOGC_ARCH, /* Related to arch-specific code */
55 LOGC_BOARD, /* Related to board-specific code */
56 LOGC_CORE, /* Related to core features (non-driver-model) */
f941c8d7
SG
57 LOGC_DM, /* Core driver-model */
58 LOGC_DT, /* Device-tree */
d8d8997b 59 LOGC_EFI, /* EFI implementation */
c3aed5db 60 LOGC_ALLOC, /* Memory allocation */
a5c13b68 61 LOGC_SANDBOX, /* Related to the sandbox board */
9f407d4e 62 LOGC_BLOBLIST, /* Bloblist */
cce61fc4 63 LOGC_DEVRES, /* Device resources (devres_... functions) */
7ca2850c
SG
64 /* Advanced Configuration and Power Interface (ACPI) */
65 LOGC_ACPI,
e9c8d49d 66
0bf96459
SG
67 LOGC_COUNT, /* Number of log categories */
68 LOGC_END, /* Sentinel value for a list of log categories */
d094a073 69 LOGC_CONT = -1, /* Use same category as in previous call */
e9c8d49d
SG
70};
71
72/* Helper to cast a uclass ID to a log category */
73static inline int log_uc_cat(enum uclass_id id)
74{
75 return (enum log_category_t)id;
76}
77
78/**
79 * _log() - Internal function to emit a new log record
80 *
81 * @cat: Category of log record (indicating which subsystem generated it)
82 * @level: Level of log record (indicating its severity)
83 * @file: File name of file where log record was generated
84 * @line: Line number in file where log record was generated
85 * @func: Function where log record was generated
86 * @fmt: printf() format string for log record
87 * @...: Optional parameters, according to the format string @fmt
88 * @return 0 if log record was emitted, -ve on error
89 */
90int _log(enum log_category_t cat, enum log_level_t level, const char *file,
ed4e933d
SG
91 int line, const char *func, const char *fmt, ...)
92 __attribute__ ((format (__printf__, 6, 7)));
e9c8d49d 93
fd42948f
SG
94static inline int _log_nop(enum log_category_t cat, enum log_level_t level,
95 const char *file, int line, const char *func,
96 const char *fmt, ...)
97 __attribute__ ((format (__printf__, 6, 7)));
98
99static inline int _log_nop(enum log_category_t cat, enum log_level_t level,
100 const char *file, int line, const char *func,
101 const char *fmt, ...)
102{
103 return 0;
104}
105
e9c8d49d
SG
106/* Define this at the top of a file to add a prefix to debug messages */
107#ifndef pr_fmt
108#define pr_fmt(fmt) fmt
109#endif
110
111/* Use a default category if this file does not supply one */
112#ifndef LOG_CATEGORY
113#define LOG_CATEGORY LOGC_NONE
114#endif
115
116/*
117 * This header may be including when CONFIG_LOG is disabled, in which case
118 * CONFIG_LOG_MAX_LEVEL is not defined. Add a check for this.
119 */
120#if CONFIG_IS_ENABLED(LOG)
121#define _LOG_MAX_LEVEL CONFIG_VAL(LOG_MAX_LEVEL)
cdd140af
SG
122#define log_err(_fmt...) log(LOG_CATEGORY, LOGL_ERR, ##_fmt)
123#define log_warning(_fmt...) log(LOG_CATEGORY, LOGL_WARNING, ##_fmt)
124#define log_notice(_fmt...) log(LOG_CATEGORY, LOGL_NOTICE, ##_fmt)
125#define log_info(_fmt...) log(LOG_CATEGORY, LOGL_INFO, ##_fmt)
126#define log_debug(_fmt...) log(LOG_CATEGORY, LOGL_DEBUG, ##_fmt)
127#define log_content(_fmt...) log(LOG_CATEGORY, LOGL_DEBUG_CONTENT, ##_fmt)
128#define log_io(_fmt...) log(LOG_CATEGORY, LOGL_DEBUG_IO, ##_fmt)
e9c8d49d
SG
129#else
130#define _LOG_MAX_LEVEL LOGL_INFO
20fd256d
HS
131#define log_err(_fmt, ...) printf(_fmt, ##__VA_ARGS__)
132#define log_warning(_fmt, ...) printf(_fmt, ##__VA_ARGS__)
133#define log_notice(_fmt, ...) printf(_fmt, ##__VA_ARGS__)
134#define log_info(_fmt, ...) printf(_fmt, ##__VA_ARGS__)
135#define log_debug(_fmt, ...) debug(_fmt, ##__VA_ARGS__)
fd42948f
SG
136#define log_content(_fmt...) log_nop(LOG_CATEGORY, \
137 LOGL_DEBUG_CONTENT, ##_fmt)
138#define log_io(_fmt...) log_nop(LOG_CATEGORY, LOGL_DEBUG_IO, ##_fmt)
e9c8d49d
SG
139#endif
140
4d8d3056 141#if CONFIG_IS_ENABLED(LOG)
f9811e85 142#ifdef LOG_DEBUG
52d3df7f 143#define _LOG_DEBUG LOGL_FORCE_DEBUG
f9811e85
SG
144#else
145#define _LOG_DEBUG 0
146#endif
4d8d3056 147
e9c8d49d
SG
148/* Emit a log record if the level is less that the maximum */
149#define log(_cat, _level, _fmt, _args...) ({ \
150 int _l = _level; \
52d3df7f
SG
151 if (CONFIG_IS_ENABLED(LOG) && \
152 (_LOG_DEBUG != 0 || _l <= _LOG_MAX_LEVEL)) \
153 _log((enum log_category_t)(_cat), \
154 (enum log_level_t)(_l | _LOG_DEBUG), __FILE__, \
155 __LINE__, __func__, \
e9c8d49d
SG
156 pr_fmt(_fmt), ##_args); \
157 })
4d8d3056
SG
158#else
159#define log(_cat, _level, _fmt, _args...)
160#endif
e9c8d49d 161
fd42948f
SG
162#define log_nop(_cat, _level, _fmt, _args...) ({ \
163 int _l = _level; \
164 _log_nop((enum log_category_t)(_cat), _l, __FILE__, __LINE__, \
165 __func__, pr_fmt(_fmt), ##_args); \
166})
167
0e98b0a6
SG
168#ifdef DEBUG
169#define _DEBUG 1
170#else
171#define _DEBUG 0
172#endif
173
174#ifdef CONFIG_SPL_BUILD
175#define _SPL_BUILD 1
176#else
177#define _SPL_BUILD 0
178#endif
179
e9c8d49d
SG
180#if !_DEBUG && CONFIG_IS_ENABLED(LOG)
181
182#define debug_cond(cond, fmt, args...) \
183 do { \
184 if (1) \
185 log(LOG_CATEGORY, LOGL_DEBUG, fmt, ##args); \
186 } while (0)
187
188#else /* _DEBUG */
189
0e98b0a6
SG
190/*
191 * Output a debug text when condition "cond" is met. The "cond" should be
192 * computed by a preprocessor in the best case, allowing for the best
193 * optimization.
194 */
195#define debug_cond(cond, fmt, args...) \
196 do { \
197 if (cond) \
198 printf(pr_fmt(fmt), ##args); \
199 } while (0)
200
e9c8d49d
SG
201#endif /* _DEBUG */
202
0e98b0a6
SG
203/* Show a message if DEBUG is defined in a file */
204#define debug(fmt, args...) \
205 debug_cond(_DEBUG, fmt, ##args)
206
207/* Show a message if not in SPL */
208#define warn_non_spl(fmt, args...) \
209 debug_cond(!_SPL_BUILD, fmt, ##args)
210
211/*
212 * An assertion is run-time check done in debug mode only. If DEBUG is not
213 * defined then it is skipped. If DEBUG is defined and the assertion fails,
214 * then it calls panic*( which may or may not reset/halt U-Boot (see
215 * CONFIG_PANIC_HANG), It is hoped that all failing assertions are found
216 * before release, and after release it is hoped that they don't matter. But
217 * in any case these failing assertions cannot be fixed with a reset (which
218 * may just do the same assertion again).
219 */
220void __assert_fail(const char *assertion, const char *file, unsigned int line,
221 const char *function);
b236f8c0
HS
222
223/**
224 * assert() - assert expression is true
225 *
226 * If the expression x evaluates to false and _DEBUG evaluates to true, a panic
227 * message is written and the system stalls. The value of _DEBUG is set to true
228 * if DEBUG is defined before including common.h.
229 *
230 * The expression x is always executed irrespective of the value of _DEBUG.
231 *
232 * @x: expression to test
233 */
0e98b0a6
SG
234#define assert(x) \
235 ({ if (!(x) && _DEBUG) \
236 __assert_fail(#x, __FILE__, __LINE__, __func__); })
237
cd01d2d5
SG
238/*
239 * This one actually gets compiled in even without DEBUG. It doesn't include the
240 * full pathname as it may be huge. Only use this when the user should be
241 * warning, similar to BUG_ON() in linux.
242 *
243 * @return true if assertion succeeded (condition is true), else false
244 */
245#define assert_noisy(x) \
246 ({ bool _val = (x); \
247 if (!_val) \
248 __assert_fail(#x, "?", __LINE__, __func__); \
249 _val; \
250 })
251
4d8d3056
SG
252#if CONFIG_IS_ENABLED(LOG) && defined(CONFIG_LOG_ERROR_RETURN)
253/*
254 * Log an error return value, possibly with a message. Usage:
255 *
256 * return log_ret(fred_call());
257 *
258 * or:
259 *
260 * return log_msg_ret("fred failed", fred_call());
261 */
3707c6ee
SG
262#define log_ret(_ret) ({ \
263 int __ret = (_ret); \
264 if (__ret < 0) \
265 log(LOG_CATEGORY, LOGL_ERR, "returning err=%d\n", __ret); \
266 __ret; \
267 })
b616cef9
SG
268#define log_msg_ret(_msg, _ret) ({ \
269 int __ret = (_ret); \
270 if (__ret < 0) \
271 log(LOG_CATEGORY, LOGL_ERR, "%s: returning err=%d\n", _msg, \
272 __ret); \
273 __ret; \
274 })
3707c6ee 275#else
4d8d3056 276/* Non-logging versions of the above which just return the error code */
3707c6ee 277#define log_ret(_ret) (_ret)
4d8d3056 278#define log_msg_ret(_msg, _ret) ((void)(_msg), _ret)
3707c6ee
SG
279#endif
280
e9c8d49d
SG
281/**
282 * struct log_rec - a single log record
283 *
284 * Holds information about a single record in the log
285 *
286 * Members marked as 'not allocated' are stored as pointers and the caller is
287 * responsible for making sure that the data pointed to is not overwritten.
288 * Memebers marked as 'allocated' are allocated (e.g. via strdup()) by the log
289 * system.
290 *
52d3df7f
SG
291 * TODO(sjg@chromium.org): Compress this struct down a bit to reduce space, e.g.
292 * a single u32 for cat, level, line and force_debug
293 *
e9c8d49d
SG
294 * @cat: Category, representing a uclass or part of U-Boot
295 * @level: Severity level, less severe is higher
52d3df7f 296 * @force_debug: Force output of debug
e9c8d49d
SG
297 * @file: Name of file where the log record was generated (not allocated)
298 * @line: Line number where the log record was generated
299 * @func: Function where the log record was generated (not allocated)
300 * @msg: Log message (allocated)
301 */
302struct log_rec {
303 enum log_category_t cat;
304 enum log_level_t level;
52d3df7f 305 bool force_debug;
e9c8d49d
SG
306 const char *file;
307 int line;
308 const char *func;
309 const char *msg;
310};
311
312struct log_device;
313
b4520300
SG
314enum log_device_flags {
315 LOGDF_ENABLE = BIT(0), /* Device is enabled */
316};
317
e9c8d49d
SG
318/**
319 * struct log_driver - a driver which accepts and processes log records
320 *
321 * @name: Name of driver
b4520300
SG
322 * @emit: Method to call to emit a log record via this device
323 * @flags: Initial value for flags (use LOGDF_ENABLE to enable on start-up)
e9c8d49d
SG
324 */
325struct log_driver {
326 const char *name;
327 /**
328 * emit() - emit a log record
329 *
330 * Called by the log system to pass a log record to a particular driver
331 * for processing. The filter is checked before calling this function.
332 */
333 int (*emit)(struct log_device *ldev, struct log_rec *rec);
b4520300 334 unsigned short flags;
e9c8d49d
SG
335};
336
337/**
338 * struct log_device - an instance of a log driver
339 *
340 * Since drivers are set up at build-time we need to have a separate device for
341 * the run-time aspects of drivers (currently just a list of filters to apply
342 * to records send to this device).
343 *
344 * @next_filter_num: Seqence number of next filter filter added (0=no filters
345 * yet). This increments with each new filter on the device, but never
346 * decrements
b4520300 347 * @flags: Flags for this filter (enum log_device_flags)
e9c8d49d
SG
348 * @drv: Pointer to driver for this device
349 * @filter_head: List of filters for this device
350 * @sibling_node: Next device in the list of all devices
351 */
352struct log_device {
b4520300
SG
353 unsigned short next_filter_num;
354 unsigned short flags;
e9c8d49d
SG
355 struct log_driver *drv;
356 struct list_head filter_head;
357 struct list_head sibling_node;
358};
359
360enum {
361 LOGF_MAX_CATEGORIES = 5, /* maximum categories per filter */
362};
363
364enum log_filter_flags {
365 LOGFF_HAS_CAT = 1 << 0, /* Filter has a category list */
366};
367
368/**
369 * struct log_filter - criterial to filter out log messages
370 *
371 * @filter_num: Sequence number of this filter. This is returned when adding a
372 * new filter, and must be provided when removing a previously added
373 * filter.
374 * @flags: Flags for this filter (LOGFF_...)
b66a924f 375 * @cat_list: List of categories to allow (terminated by %LOGC_END). If empty
e9c8d49d
SG
376 * then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries
377 * can be provided
378 * @max_level: Maximum log level to allow
379 * @file_list: List of files to allow, separated by comma. If NULL then all
380 * files are permitted
381 * @sibling_node: Next filter in the list of filters for this log device
382 */
383struct log_filter {
384 int filter_num;
385 int flags;
386 enum log_category_t cat_list[LOGF_MAX_CATEGORIES];
387 enum log_level_t max_level;
388 const char *file_list;
389 struct list_head sibling_node;
390};
391
392#define LOG_DRIVER(_name) \
393 ll_entry_declare(struct log_driver, _name, log_driver)
394
3d03ab63
SG
395/* Get a pointer to a given driver */
396#define LOG_GET_DRIVER(__name) \
397 ll_entry_get(struct log_driver, __name, log_driver)
398
f941c8d7
SG
399/**
400 * log_get_cat_name() - Get the name of a category
401 *
402 * @cat: Category to look up
c2e4e7e6
SG
403 * @return category name (which may be a uclass driver name) if found, or
404 * "<invalid>" if invalid, or "<missing>" if not found
f941c8d7
SG
405 */
406const char *log_get_cat_name(enum log_category_t cat);
407
408/**
409 * log_get_cat_by_name() - Look up a category by name
410 *
411 * @name: Name to look up
412 * @return category ID, or LOGC_NONE if not found
413 */
414enum log_category_t log_get_cat_by_name(const char *name);
415
416/**
417 * log_get_level_name() - Get the name of a log level
418 *
419 * @level: Log level to look up
420 * @return log level name (in ALL CAPS)
421 */
422const char *log_get_level_name(enum log_level_t level);
423
424/**
425 * log_get_level_by_name() - Look up a log level by name
426 *
427 * @name: Name to look up
428 * @return log level ID, or LOGL_NONE if not found
429 */
430enum log_level_t log_get_level_by_name(const char *name);
431
3102c1d2
SA
432/**
433 * log_device_find_by_name() - Look up a log device by its driver's name
434 *
435 * @drv_name: Name of the driver
436 * @return the log device, or NULL if not found
437 */
438struct log_device *log_device_find_by_name(const char *drv_name);
439
440/**
441 * log_has_cat() - check if a log category exists within a list
442 *
443 * @cat_list: List of categories to check, at most %LOGF_MAX_CATEGORIES entries
444 * long, terminated by %LC_END if fewer
445 * @cat: Category to search for
446 *
447 * Return: ``true`` if @cat is in @cat_list, else ``false``
448 */
449bool log_has_cat(enum log_category_t cat_list[], enum log_category_t cat);
450
451/**
452 * log_has_file() - check if a file is with a list
453 *
454 * @file_list: List of files to check, separated by comma
455 * @file: File to check for. This string is matched against the end of each
456 * file in the list, i.e. ignoring any preceding path. The list is
457 * intended to consist of relative pathnames, e.g. common/main.c,cmd/log.c
458 *
459 * Return: ``true`` if @file is in @file_list, else ``false``
460 */
461bool log_has_file(const char *file_list, const char *file);
462
3b73e8d0
SG
463/* Log format flags (bit numbers) for gd->log_fmt. See log_fmt_chars */
464enum log_fmt {
465 LOGF_CAT = 0,
466 LOGF_LEVEL,
467 LOGF_FILE,
468 LOGF_LINE,
469 LOGF_FUNC,
470 LOGF_MSG,
471
472 LOGF_COUNT,
3b73e8d0
SG
473 LOGF_ALL = 0x3f,
474};
475
ef11ed82 476/* Handle the 'log test' command */
09140113 477int do_log_test(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]);
ef11ed82 478
a02f84ee
SA
479/**
480 * log_add_filter_flags() - Add a new filter to a log device, specifying flags
481 *
482 * @drv_name: Driver name to add the filter to (since each driver only has a
483 * single device)
484 * @flags: Flags for this filter (LOGFF_...)
485 * @cat_list: List of categories to allow (terminated by %LOGC_END). If empty
486 * then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries
487 * can be provided
488 * @max_level: Maximum log level to allow
489 * @file_list: List of files to allow, separated by comma. If NULL then all
490 * files are permitted
491 * @return the sequence number of the new filter (>=0) if the filter was added,
492 * or a -ve value on error
493 */
494int log_add_filter_flags(const char *drv_name, enum log_category_t cat_list[],
495 enum log_level_t max_level, const char *file_list,
496 int flags);
497
e9c8d49d
SG
498/**
499 * log_add_filter() - Add a new filter to a log device
500 *
501 * @drv_name: Driver name to add the filter to (since each driver only has a
502 * single device)
b66a924f 503 * @cat_list: List of categories to allow (terminated by %LOGC_END). If empty
e9c8d49d
SG
504 * then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries
505 * can be provided
506 * @max_level: Maximum log level to allow
507 * @file_list: List of files to allow, separated by comma. If NULL then all
508 * files are permitted
509 * @return the sequence number of the new filter (>=0) if the filter was added,
510 * or a -ve value on error
511 */
a02f84ee
SA
512static inline int log_add_filter(const char *drv_name,
513 enum log_category_t cat_list[],
514 enum log_level_t max_level,
515 const char *file_list)
516{
517 return log_add_filter_flags(drv_name, cat_list, max_level, file_list,
518 0);
519}
e9c8d49d
SG
520
521/**
522 * log_remove_filter() - Remove a filter from a log device
523 *
524 * @drv_name: Driver name to remove the filter from (since each driver only has
525 * a single device)
526 * @filter_num: Filter number to remove (as returned by log_add_filter())
527 * @return 0 if the filter was removed, -ENOENT if either the driver or the
528 * filter number was not found
529 */
530int log_remove_filter(const char *drv_name, int filter_num);
531
3d03ab63
SG
532/**
533 * log_device_set_enable() - Enable or disable a log device
534 *
535 * Devices are referenced by their driver, so use LOG_GET_DRIVER(name) to pass
536 * the driver to this function. For example if the driver is declared with
537 * LOG_DRIVER(wibble) then pass LOG_GET_DRIVER(wibble) here.
538 *
539 * @drv: Driver of device to enable
540 * @enable: true to enable, false to disable
541 * @return 0 if OK, -ENOENT if the driver was not found
542 */
543int log_device_set_enable(struct log_driver *drv, bool enable);
544
e9c8d49d
SG
545#if CONFIG_IS_ENABLED(LOG)
546/**
547 * log_init() - Set up the log system ready for use
548 *
549 * @return 0 if OK, -ENOMEM if out of memory
550 */
551int log_init(void);
552#else
553static inline int log_init(void)
554{
555 return 0;
556}
557#endif
558
3c21d773
HS
559/**
560 * log_get_default_format() - get default log format
561 *
562 * The default log format is configurable via
563 * CONFIG_LOGF_FILE, CONFIG_LOGF_LINE, CONFIG_LOGF_FUNC.
564 *
565 * Return: default log format
566 */
567static inline int log_get_default_format(void)
568{
569 return BIT(LOGF_MSG) |
570 (IS_ENABLED(CONFIG_LOGF_FILE) ? BIT(LOGF_FILE) : 0) |
571 (IS_ENABLED(CONFIG_LOGF_LINE) ? BIT(LOGF_LINE) : 0) |
572 (IS_ENABLED(CONFIG_LOGF_FUNC) ? BIT(LOGF_FUNC) : 0);
573}
574
0e98b0a6 575#endif
This page took 0.369393 seconds and 4 git commands to generate.