[J-u-boot.git] / include / log.h

/*
 * Logging support
 *
 * Copyright (c) 2017 Google, Inc
 * Written by Simon Glass <[email protected]>
 *
 * SPDX-License-Identifier:	GPL-2.0+
 */

#ifndef __LOG_H
#define __LOG_H

#include <dm/uclass-id.h>
#include <linux/list.h>

/** Log levels supported, ranging from most to least important */
enum log_level_t {
	LOGL_EMERG = 0,		/*U-Boot is unstable */
	LOGL_ALERT,		/* Action must be taken immediately */
	LOGL_CRIT,		/* Critical conditions */
	LOGL_ERR,		/* Error that prevents something from working */
	LOGL_WARNING,		/* Warning may prevent optimial operation */
	LOGL_NOTICE,		/* Normal but significant condition, printf() */
	LOGL_INFO,		/* General information message */
	LOGL_DEBUG,		/* Basic debug-level message */
	LOGL_DEBUG_CONTENT,	/* Debug message showing full message content */
	LOGL_DEBUG_IO,		/* Debug message showing hardware I/O access */

	LOGL_COUNT,
	LOGL_FIRST = LOGL_EMERG,
	LOGL_MAX = LOGL_DEBUG,
};

/**
 * Log categories supported. Most of these correspond to uclasses (i.e.
 * enum uclass_id) but there are also some more generic categories
 */
enum log_category_t {
	LOGC_FIRST = 0,	/* First part mirrors UCLASS_... */

	LOGC_NONE = UCLASS_COUNT,
	LOGC_ARCH,
	LOGC_BOARD,
	LOGC_CORE,
	LOGC_DT,

	LOGC_COUNT,
	LOGC_END,
};

/* Helper to cast a uclass ID to a log category */
static inline int log_uc_cat(enum uclass_id id)
{
	return (enum log_category_t)id;
}

/**
 * _log() - Internal function to emit a new log record
 *
 * @cat: Category of log record (indicating which subsystem generated it)
 * @level: Level of log record (indicating its severity)
 * @file: File name of file where log record was generated
 * @line: Line number in file where log record was generated
 * @func: Function where log record was generated
 * @fmt: printf() format string for log record
 * @...: Optional parameters, according to the format string @fmt
 * @return 0 if log record was emitted, -ve on error
 */
int _log(enum log_category_t cat, enum log_level_t level, const char *file,
	 int line, const char *func, const char *fmt, ...);

/* Define this at the top of a file to add a prefix to debug messages */
#ifndef pr_fmt
#define pr_fmt(fmt) fmt
#endif

/* Use a default category if this file does not supply one */
#ifndef LOG_CATEGORY
#define LOG_CATEGORY LOGC_NONE
#endif

/*
 * This header may be including when CONFIG_LOG is disabled, in which case
 * CONFIG_LOG_MAX_LEVEL is not defined. Add a check for this.
 */
#if CONFIG_IS_ENABLED(LOG)
#define _LOG_MAX_LEVEL CONFIG_VAL(LOG_MAX_LEVEL)
#else
#define _LOG_MAX_LEVEL LOGL_INFO
#endif

/* Emit a log record if the level is less that the maximum */
#define log(_cat, _level, _fmt, _args...) ({ \
	int _l = _level; \
	if (_l <= _LOG_MAX_LEVEL) \
		_log((enum log_category_t)(_cat), _l, __FILE__, __LINE__, \
		      __func__, \
		      pr_fmt(_fmt), ##_args); \
	})

#ifdef DEBUG
#define _DEBUG	1
#else
#define _DEBUG	0
#endif

#ifdef CONFIG_SPL_BUILD
#define _SPL_BUILD	1
#else
#define _SPL_BUILD	0
#endif

#if !_DEBUG && CONFIG_IS_ENABLED(LOG)

#define debug_cond(cond, fmt, args...)			\
	do {						\
		if (1)					\
			log(LOG_CATEGORY, LOGL_DEBUG, fmt, ##args); \
	} while (0)

#else /* _DEBUG */

/*
 * Output a debug text when condition "cond" is met. The "cond" should be
 * computed by a preprocessor in the best case, allowing for the best
 * optimization.
 */
#define debug_cond(cond, fmt, args...)			\
	do {						\
		if (cond)				\
			printf(pr_fmt(fmt), ##args);	\
	} while (0)

#endif /* _DEBUG */

/* Show a message if DEBUG is defined in a file */
#define debug(fmt, args...)			\
	debug_cond(_DEBUG, fmt, ##args)

/* Show a message if not in SPL */
#define warn_non_spl(fmt, args...)			\
	debug_cond(!_SPL_BUILD, fmt, ##args)

/*
 * An assertion is run-time check done in debug mode only. If DEBUG is not
 * defined then it is skipped. If DEBUG is defined and the assertion fails,
 * then it calls panic*( which may or may not reset/halt U-Boot (see
 * CONFIG_PANIC_HANG), It is hoped that all failing assertions are found
 * before release, and after release it is hoped that they don't matter. But
 * in any case these failing assertions cannot be fixed with a reset (which
 * may just do the same assertion again).
 */
void __assert_fail(const char *assertion, const char *file, unsigned int line,
		   const char *function);
#define assert(x) \
	({ if (!(x) && _DEBUG) \
		__assert_fail(#x, __FILE__, __LINE__, __func__); })

/**
 * struct log_rec - a single log record
 *
 * Holds information about a single record in the log
 *
 * Members marked as 'not allocated' are stored as pointers and the caller is
 * responsible for making sure that the data pointed to is not overwritten.
 * Memebers marked as 'allocated' are allocated (e.g. via strdup()) by the log
 * system.
 *
 * @cat: Category, representing a uclass or part of U-Boot
 * @level: Severity level, less severe is higher
 * @file: Name of file where the log record was generated (not allocated)
 * @line: Line number where the log record was generated
 * @func: Function where the log record was generated (not allocated)
 * @msg: Log message (allocated)
 */
struct log_rec {
	enum log_category_t cat;
	enum log_level_t level;
	const char *file;
	int line;
	const char *func;
	const char *msg;
};

struct log_device;

/**
 * struct log_driver - a driver which accepts and processes log records
 *
 * @name: Name of driver
 */
struct log_driver {
	const char *name;
	/**
	 * emit() - emit a log record
	 *
	 * Called by the log system to pass a log record to a particular driver
	 * for processing. The filter is checked before calling this function.
	 */
	int (*emit)(struct log_device *ldev, struct log_rec *rec);
};

/**
 * struct log_device - an instance of a log driver
 *
 * Since drivers are set up at build-time we need to have a separate device for
 * the run-time aspects of drivers (currently just a list of filters to apply
 * to records send to this device).
 *
 * @next_filter_num: Seqence number of next filter filter added (0=no filters
 *	yet). This increments with each new filter on the device, but never
 *	decrements
 * @drv: Pointer to driver for this device
 * @filter_head: List of filters for this device
 * @sibling_node: Next device in the list of all devices
 */
struct log_device {
	int next_filter_num;
	struct log_driver *drv;
	struct list_head filter_head;
	struct list_head sibling_node;
};

enum {
	LOGF_MAX_CATEGORIES = 5,	/* maximum categories per filter */
};

enum log_filter_flags {
	LOGFF_HAS_CAT		= 1 << 0,	/* Filter has a category list */
};

/**
 * struct log_filter - criterial to filter out log messages
 *
 * @filter_num: Sequence number of this filter.  This is returned when adding a
 *	new filter, and must be provided when removing a previously added
 *	filter.
 * @flags: Flags for this filter (LOGFF_...)
 * @cat_list: List of categories to allow (terminated by LOGC_none). If empty
 *	then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries
 *	can be provided
 * @max_level: Maximum log level to allow
 * @file_list: List of files to allow, separated by comma. If NULL then all
 *	files are permitted
 * @sibling_node: Next filter in the list of filters for this log device
 */
struct log_filter {
	int filter_num;
	int flags;
	enum log_category_t cat_list[LOGF_MAX_CATEGORIES];
	enum log_level_t max_level;
	const char *file_list;
	struct list_head sibling_node;
};

#define LOG_DRIVER(_name) \
	ll_entry_declare(struct log_driver, _name, log_driver)

/**
 * log_add_filter() - Add a new filter to a log device
 *
 * @drv_name: Driver name to add the filter to (since each driver only has a
 *	single device)
 * @cat_list: List of categories to allow (terminated by LOGC_none). If empty
 *	then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries
 *	can be provided
 * @max_level: Maximum log level to allow
 * @file_list: List of files to allow, separated by comma. If NULL then all
 *	files are permitted
 * @return the sequence number of the new filter (>=0) if the filter was added,
 *	or a -ve value on error
 */
int log_add_filter(const char *drv_name, enum log_category_t cat_list[],
		   enum log_level_t max_level, const char *file_list);

/**
 * log_remove_filter() - Remove a filter from a log device
 *
 * @drv_name: Driver name to remove the filter from (since each driver only has
 *	a single device)
 * @filter_num: Filter number to remove (as returned by log_add_filter())
 * @return 0 if the filter was removed, -ENOENT if either the driver or the
 *	filter number was not found
 */
int log_remove_filter(const char *drv_name, int filter_num);

#if CONFIG_IS_ENABLED(LOG)
/**
 * log_init() - Set up the log system ready for use
 *
 * @return 0 if OK, -ENOMEM if out of memory
 */
int log_init(void);
#else
static inline int log_init(void)
{
	return 0;
}
#endif

#endif
Commit	Line	Data
0e98b0a6 SG	1	/*
	2	* Logging support
	3	*
	4	* Copyright (c) 2017 Google, Inc
	5	* Written by Simon Glass <[email protected]>
	6	*
	7	* SPDX-License-Identifier: GPL-2.0+
	8	*/
	9
	10	#ifndef __LOG_H
	11	#define __LOG_H
	12
e9c8d49d SG	13	#include <dm/uclass-id.h>
	14	#include <linux/list.h>
	15
	16	/** Log levels supported, ranging from most to least important */
	17	enum 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	*/
	38	enum 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 */
	52	static 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	*/
	69	int _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
0e98b0a6 SG	101	#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
e9c8d49d SG	113	#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
0e98b0a6 SG	123	/*
	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
e9c8d49d SG	134	#endif /* _DEBUG */
e9c8d49d SG	135
0e98b0a6 SG	136	/* 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	*/
	153	void __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
e9c8d49d SG	159	/**
	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	*/
	176	struct 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
	185	struct log_device;
	186
	187	/**
	188	* struct log_driver - a driver which accepts and processes log records
	189	*
	190	* @name: Name of driver
	191	*/
	192	struct 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	*/
	217	struct 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
224	enum {
225	LOGF_MAX_CATEGORIES = 5, /* maximum categories per filter */
226	};
227
228	enum 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	*/
247	struct 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
259	/**
260	* log_add_filter() - Add a new filter to a log device
261	*
262	* @drv_name: Driver name to add the filter to (since each driver only has a
263	* single device)
264	* @cat_list: List of categories to allow (terminated by LOGC_none). If empty
265	* then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries
266	* can be provided
267	* @max_level: Maximum log level to allow
268	* @file_list: List of files to allow, separated by comma. If NULL then all
269	* files are permitted
270	* @return the sequence number of the new filter (>=0) if the filter was added,
271	* or a -ve value on error
272	*/
273	int log_add_filter(const char *drv_name, enum log_category_t cat_list[],
274	enum log_level_t max_level, const char *file_list);
275
276	/**
277	* log_remove_filter() - Remove a filter from a log device
278	*
279	* @drv_name: Driver name to remove the filter from (since each driver only has
280	* a single device)
281	* @filter_num: Filter number to remove (as returned by log_add_filter())
282	* @return 0 if the filter was removed, -ENOENT if either the driver or the
283	* filter number was not found
284	*/
285	int log_remove_filter(const char *drv_name, int filter_num);
286
287	#if CONFIG_IS_ENABLED(LOG)
288	/**
289	* log_init() - Set up the log system ready for use
290	*
291	* @return 0 if OK, -ENOMEM if out of memory
292	*/
293	int log_init(void);
294	#else
295	static inline int log_init(void)
296	{
297	return 0;
298	}
299	#endif
300
0e98b0a6	301	#endif