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