doc/README.log

   1 Logging in U-Boot
   2 =================
   3
   4 Introduction
   5 ------------
   6
   7 U-Boot's internal operation involves many different steps and actions. From
   8 setting up the board to displaying a start-up screen to loading an Operating
   9 System, there are many component parts each with many actions.
  10
  11 Most of the time this internal detail is not useful. Displaying it on the
  12 console would delay booting (U-Boot's primary purpose) and confuse users.
  13
  14 But for digging into what is happening in a particular area, or for debugging
  15 a problem it is often useful to see what U-Boot is doing in more detail than
  16 is visible from the basic console output.
  17
  18 U-Boot's logging feature aims to satisfy this goal for both users and
  19 developers.
  20
  21
  22 Logging levels
  23 --------------
  24
  25 There are a number logging levels available, in increasing order of verbosity:
  26
  27    LOGL_EMERG   - Printed before U-Boot halts
  28    LOGL_ALERT   - Indicates action must be taken immediate or U-Boot will crash
  29    LOGL_CRIT    - Indicates a critical error that will cause boot failure
  30    LOGL_ERR     - Indicates an error that may cause boot failure
  31    LOGL_WARNING - Warning about an unexpected condition
  32    LOGL_NOTE    - Important information about progress
  33    LOGL_INFO    - Information about normal boot progress
  34    LOGL_DEBUG   - Debug information (useful for debugging a driver or subsystem)
  35    LOGL_DEBUG_CONTENT   - Debug message showing full message content
  36    LOGL_DEBUG_IO        - Debug message showing hardware I/O access
  37
  38
  39 Logging category
  40 ----------------
  41
  42 Logging can come from a wide variety of places within U-Boot. Each log message
  43 has a category which is intended to allow messages to be filtered according to
  44 their source.
  45
  46 The following main categories are defined:
  47
  48    LOGC_NONE    - Unknown category (e.g. a debug() statement)
  49    UCLASS_...   - Related to a particular uclass (e.g. UCLASS_USB)
  50    LOGC_ARCH    - Related to architecture-specific code
  51    LOGC_BOARD   - Related to board-specific code
  52    LOGC_CORE    - Related to core driver-model support
  53    LOGC_DT      - Related to device tree control
  54
  55
  56 Enabling logging
  57 ----------------
  58
  59 The following options are used to enable logging at compile time:
  60
  61    CONFIG_LOG           - Enables the logging system
  62    CONFIG_MAX_LOG_LEVEL - Max log level to build (anything higher is compiled
  63                                 out)
  64    CONFIG_LOG_CONSOLE   - Enable writing log records to the console
  65
  66 If CONFIG_LOG is not set, then no logging will be available.
  67
  68 The above have SPL versions also, e.g. CONFIG_SPL_MAX_LOG_LEVEL.
  69
  70
  71 Using DEBUG
  72 -----------
  73
  74 U-Boot has traditionally used a #define called DEBUG to enable debugging on a
  75 file-by-file basis. The debug() macro compiles to a printf() statement if
  76 DEBUG is enabled, and an empty statement if not.
  77
  78 With logging enabled, debug() statements are interpreted as logging output
  79 with a level of LOGL_DEBUG and a category of LOGC_NONE.
  80
  81 The logging facilities are intended to replace DEBUG, but if DEBUG is defined
  82 at the top of a file, then it takes precedence. This means that debug()
  83 statements will result in output to the console and this output will not be
  84 logged.
  85
  86
  87 Logging destinations
  88 --------------------
  89
  90 If logging information goes nowhere then it serves no purpose. U-Boot provides
  91 several possible determinations for logging information, all of which can be
  92 enabled or disabled independently:
  93
  94    console - goes to stdout
  95
  96
  97 Filters
  98 -------
  99
 100 Filters are attached to log drivers to control what those drivers emit. Only
 101 records that pass through the filter make it to the driver.
 102
 103 Filters can be based on several criteria:
 104
 105    - maximum log level
 106    - in a set of categories
 107    - in a set of files
 108
 109 If no filters are attached to a driver then a default filter is used, which
 110 limits output to records with a level less than CONFIG_LOG_MAX_LEVEL.
 111
 112
 113 Logging statements
 114 ------------------
 115
 116 The main logging function is:
 117
 118    log(category, level, format_string, ...)
 119
 120 Also debug() and error() will generate log records  - these use LOG_CATEGORY
 121 as the category, so you should #define this right at the top of the source
 122 file to ensure the category is correct.
 123
 124
 125 Code size
 126 ---------
 127
 128 Code size impact depends largely on what is enabled. The following numbers are
 129 for snow, which is a Thumb-2 board:
 130
 131 This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0
 132 CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0
 133 CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0
 134
 135 The last option turns every debug() statement into a logging call, which
 136 bloats the code hugely. The advantage is that it is then possible to enable
 137 all logging within U-Boot.
 138
 139
 140 To Do
 141 -----
 142
 143 There are lots of useful additions that could be made. None of the below is
 144 implemented! If you do one, please add a test in test/py/tests/test_log.py
 145
 146 Convenience functions to support setting the category:
 147
 148    log_arch(level, format_string, ...) - category LOGC_ARCH
 149    log_board(level, format_string, ...) - category LOGC_BOARD
 150    log_core(level, format_string, ...) - category LOGC_CORE
 151    log_dt(level, format_string, ...) - category LOGC_DT
 152
 153 Convenience functions to support a category defined for a single file, for
 154 example:
 155
 156    #define LOG_CATEGORY   UCLASS_USB
 157
 158 all of these can use LOG_CATEGORY as the category, and a log level
 159 corresponding to the function name:
 160
 161    logc(level, format_string, ...)
 162
 163 More logging destinations:
 164
 165    device - goes to a device (e.g. serial)
 166    buffer - recorded in a memory buffer
 167
 168 Convert debug() statements in the code to log() statements
 169
 170 Support making printf() emit log statements a L_INFO level
 171
 172 Convert error() statements in the code to log() statements
 173
 174 Figure out what to do with BUG(), BUG_ON() and warn_non_spl()
 175
 176 Figure out what to do with assert()
 177
 178 Add a way to browse log records
 179
 180 Add a way to record log records for browsing using an external tool
 181
 182 Add commands to add and remove filters
 183
 184 Add commands to add and remove log devices
 185
 186 Allow sharing of printf format strings in log records to reduce storage size
 187 for large numbers of log records
 188
 189 Add a command-line option to sandbox to set the default logging level
 190
 191 Convert core driver model code to use logging
 192
 193 Convert uclasses to use logging with the correct category
 194
 195 Consider making log() calls emit an automatic newline, perhaps with a logn()
 196    function to avoid that
 197
 198 Passing log records through to linux (e.g. via device tree /chosen)
 199
 200 Provide a command to access the number of log records generated, and the
 201 number dropped due to them being generated before the log system was ready.
 202
 203 Add a printf() format string pragma so that log statements are checked properly
 204
 205 Enhance the log console driver to show level / category / file / line
 206 information
 207
 208 Add a command to add new log records and delete existing records.
 209
 210 Provide additional log() functions - e.g. logc() to specify the category
 211
 212 --
 213 Simon Glass <sjg@chromium.org>
 214 15-Sep-17