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