blob: 8083b64831d9208726777753d6ed6955173a3812 [file] [log] [blame]
Simon Glass0e98b0a2017-12-04 13:48:20 -07001/*
2 * Logging support
3 *
4 * Copyright (c) 2017 Google, Inc
5 * Written by Simon Glass <sjg@chromium.org>
6 *
7 * SPDX-License-Identifier: GPL-2.0+
8 */
9
10#ifndef __LOG_H
11#define __LOG_H
12
Simon Glasse9c8d492017-12-04 13:48:24 -070013#include <dm/uclass-id.h>
14#include <linux/list.h>
15
16/** Log levels supported, ranging from most to least important */
17enum log_level_t {
18 LOGL_EMERG = 0, /*U-Boot is unstable */
19 LOGL_ALERT, /* Action must be taken immediately */
20 LOGL_CRIT, /* Critical conditions */
21 LOGL_ERR, /* Error that prevents something from working */
22 LOGL_WARNING, /* Warning may prevent optimial operation */
23 LOGL_NOTICE, /* Normal but significant condition, printf() */
24 LOGL_INFO, /* General information message */
25 LOGL_DEBUG, /* Basic debug-level message */
26 LOGL_DEBUG_CONTENT, /* Debug message showing full message content */
27 LOGL_DEBUG_IO, /* Debug message showing hardware I/O access */
28
29 LOGL_COUNT,
30 LOGL_FIRST = LOGL_EMERG,
31 LOGL_MAX = LOGL_DEBUG,
32};
33
34/**
35 * Log categories supported. Most of these correspond to uclasses (i.e.
36 * enum uclass_id) but there are also some more generic categories
37 */
38enum log_category_t {
39 LOGC_FIRST = 0, /* First part mirrors UCLASS_... */
40
41 LOGC_NONE = UCLASS_COUNT,
42 LOGC_ARCH,
43 LOGC_BOARD,
44 LOGC_CORE,
45 LOGC_DT,
46
47 LOGC_COUNT,
48 LOGC_END,
49};
50
51/* Helper to cast a uclass ID to a log category */
52static inline int log_uc_cat(enum uclass_id id)
53{
54 return (enum log_category_t)id;
55}
56
57/**
58 * _log() - Internal function to emit a new log record
59 *
60 * @cat: Category of log record (indicating which subsystem generated it)
61 * @level: Level of log record (indicating its severity)
62 * @file: File name of file where log record was generated
63 * @line: Line number in file where log record was generated
64 * @func: Function where log record was generated
65 * @fmt: printf() format string for log record
66 * @...: Optional parameters, according to the format string @fmt
67 * @return 0 if log record was emitted, -ve on error
68 */
69int _log(enum log_category_t cat, enum log_level_t level, const char *file,
70 int line, const char *func, const char *fmt, ...);
71
72/* Define this at the top of a file to add a prefix to debug messages */
73#ifndef pr_fmt
74#define pr_fmt(fmt) fmt
75#endif
76
77/* Use a default category if this file does not supply one */
78#ifndef LOG_CATEGORY
79#define LOG_CATEGORY LOGC_NONE
80#endif
81
82/*
83 * This header may be including when CONFIG_LOG is disabled, in which case
84 * CONFIG_LOG_MAX_LEVEL is not defined. Add a check for this.
85 */
86#if CONFIG_IS_ENABLED(LOG)
87#define _LOG_MAX_LEVEL CONFIG_VAL(LOG_MAX_LEVEL)
88#else
89#define _LOG_MAX_LEVEL LOGL_INFO
90#endif
91
92/* Emit a log record if the level is less that the maximum */
93#define log(_cat, _level, _fmt, _args...) ({ \
94 int _l = _level; \
95 if (_l <= _LOG_MAX_LEVEL) \
96 _log((enum log_category_t)(_cat), _l, __FILE__, __LINE__, \
97 __func__, \
98 pr_fmt(_fmt), ##_args); \
99 })
100
Simon Glass0e98b0a2017-12-04 13:48:20 -0700101#ifdef DEBUG
102#define _DEBUG 1
103#else
104#define _DEBUG 0
105#endif
106
107#ifdef CONFIG_SPL_BUILD
108#define _SPL_BUILD 1
109#else
110#define _SPL_BUILD 0
111#endif
112
Simon Glasse9c8d492017-12-04 13:48:24 -0700113#if !_DEBUG && CONFIG_IS_ENABLED(LOG)
114
115#define debug_cond(cond, fmt, args...) \
116 do { \
117 if (1) \
118 log(LOG_CATEGORY, LOGL_DEBUG, fmt, ##args); \
119 } while (0)
120
121#else /* _DEBUG */
122
Simon Glass0e98b0a2017-12-04 13:48:20 -0700123/*
124 * Output a debug text when condition "cond" is met. The "cond" should be
125 * computed by a preprocessor in the best case, allowing for the best
126 * optimization.
127 */
128#define debug_cond(cond, fmt, args...) \
129 do { \
130 if (cond) \
131 printf(pr_fmt(fmt), ##args); \
132 } while (0)
133
Simon Glasse9c8d492017-12-04 13:48:24 -0700134#endif /* _DEBUG */
135
Simon Glass0e98b0a2017-12-04 13:48:20 -0700136/* Show a message if DEBUG is defined in a file */
137#define debug(fmt, args...) \
138 debug_cond(_DEBUG, fmt, ##args)
139
140/* Show a message if not in SPL */
141#define warn_non_spl(fmt, args...) \
142 debug_cond(!_SPL_BUILD, fmt, ##args)
143
144/*
145 * An assertion is run-time check done in debug mode only. If DEBUG is not
146 * defined then it is skipped. If DEBUG is defined and the assertion fails,
147 * then it calls panic*( which may or may not reset/halt U-Boot (see
148 * CONFIG_PANIC_HANG), It is hoped that all failing assertions are found
149 * before release, and after release it is hoped that they don't matter. But
150 * in any case these failing assertions cannot be fixed with a reset (which
151 * may just do the same assertion again).
152 */
153void __assert_fail(const char *assertion, const char *file, unsigned int line,
154 const char *function);
155#define assert(x) \
156 ({ if (!(x) && _DEBUG) \
157 __assert_fail(#x, __FILE__, __LINE__, __func__); })
158
Simon Glasse9c8d492017-12-04 13:48:24 -0700159/**
160 * struct log_rec - a single log record
161 *
162 * Holds information about a single record in the log
163 *
164 * Members marked as 'not allocated' are stored as pointers and the caller is
165 * responsible for making sure that the data pointed to is not overwritten.
166 * Memebers marked as 'allocated' are allocated (e.g. via strdup()) by the log
167 * system.
168 *
169 * @cat: Category, representing a uclass or part of U-Boot
170 * @level: Severity level, less severe is higher
171 * @file: Name of file where the log record was generated (not allocated)
172 * @line: Line number where the log record was generated
173 * @func: Function where the log record was generated (not allocated)
174 * @msg: Log message (allocated)
175 */
176struct log_rec {
177 enum log_category_t cat;
178 enum log_level_t level;
179 const char *file;
180 int line;
181 const char *func;
182 const char *msg;
183};
184
185struct log_device;
186
187/**
188 * struct log_driver - a driver which accepts and processes log records
189 *
190 * @name: Name of driver
191 */
192struct log_driver {
193 const char *name;
194 /**
195 * emit() - emit a log record
196 *
197 * Called by the log system to pass a log record to a particular driver
198 * for processing. The filter is checked before calling this function.
199 */
200 int (*emit)(struct log_device *ldev, struct log_rec *rec);
201};
202
203/**
204 * struct log_device - an instance of a log driver
205 *
206 * Since drivers are set up at build-time we need to have a separate device for
207 * the run-time aspects of drivers (currently just a list of filters to apply
208 * to records send to this device).
209 *
210 * @next_filter_num: Seqence number of next filter filter added (0=no filters
211 * yet). This increments with each new filter on the device, but never
212 * decrements
213 * @drv: Pointer to driver for this device
214 * @filter_head: List of filters for this device
215 * @sibling_node: Next device in the list of all devices
216 */
217struct log_device {
218 int next_filter_num;
219 struct log_driver *drv;
220 struct list_head filter_head;
221 struct list_head sibling_node;
222};
223
224enum {
225 LOGF_MAX_CATEGORIES = 5, /* maximum categories per filter */
226};
227
228enum log_filter_flags {
229 LOGFF_HAS_CAT = 1 << 0, /* Filter has a category list */
230};
231
232/**
233 * struct log_filter - criterial to filter out log messages
234 *
235 * @filter_num: Sequence number of this filter. This is returned when adding a
236 * new filter, and must be provided when removing a previously added
237 * filter.
238 * @flags: Flags for this filter (LOGFF_...)
239 * @cat_list: List of categories to allow (terminated by LOGC_none). If empty
240 * then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries
241 * can be provided
242 * @max_level: Maximum log level to allow
243 * @file_list: List of files to allow, separated by comma. If NULL then all
244 * files are permitted
245 * @sibling_node: Next filter in the list of filters for this log device
246 */
247struct log_filter {
248 int filter_num;
249 int flags;
250 enum log_category_t cat_list[LOGF_MAX_CATEGORIES];
251 enum log_level_t max_level;
252 const char *file_list;
253 struct list_head sibling_node;
254};
255
256#define LOG_DRIVER(_name) \
257 ll_entry_declare(struct log_driver, _name, log_driver)
258
Simon Glassef11ed82017-12-04 13:48:27 -0700259/* Handle the 'log test' command */
260int do_log_test(cmd_tbl_t *cmdtp, int flag, int argc, char *const argv[]);
261
Simon Glasse9c8d492017-12-04 13:48:24 -0700262/**
263 * log_add_filter() - Add a new filter to a log device
264 *
265 * @drv_name: Driver name to add the filter to (since each driver only has a
266 * single device)
267 * @cat_list: List of categories to allow (terminated by LOGC_none). If empty
268 * then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries
269 * can be provided
270 * @max_level: Maximum log level to allow
271 * @file_list: List of files to allow, separated by comma. If NULL then all
272 * files are permitted
273 * @return the sequence number of the new filter (>=0) if the filter was added,
274 * or a -ve value on error
275 */
276int log_add_filter(const char *drv_name, enum log_category_t cat_list[],
277 enum log_level_t max_level, const char *file_list);
278
279/**
280 * log_remove_filter() - Remove a filter from a log device
281 *
282 * @drv_name: Driver name to remove the filter from (since each driver only has
283 * a single device)
284 * @filter_num: Filter number to remove (as returned by log_add_filter())
285 * @return 0 if the filter was removed, -ENOENT if either the driver or the
286 * filter number was not found
287 */
288int log_remove_filter(const char *drv_name, int filter_num);
289
290#if CONFIG_IS_ENABLED(LOG)
291/**
292 * log_init() - Set up the log system ready for use
293 *
294 * @return 0 if OK, -ENOMEM if out of memory
295 */
296int log_init(void);
297#else
298static inline int log_init(void)
299{
300 return 0;
301}
302#endif
303
Simon Glass0e98b0a2017-12-04 13:48:20 -0700304#endif