include/log.h

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