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 Log commands
  72 ------------
  73
  74 The 'log' command provides access to several features:
  75
  76    level - access the default log level
  77    format - access the console log format
  78    rec - output a log record
  79    test - run tests
  80
  81 Type 'help log' for details.
  82
  83
  84 Using DEBUG
  85 -----------
  86
  87 U-Boot has traditionally used a #define called DEBUG to enable debugging on a
  88 file-by-file basis. The debug() macro compiles to a printf() statement if
  89 DEBUG is enabled, and an empty statement if not.
  90
  91 With logging enabled, debug() statements are interpreted as logging output
  92 with a level of LOGL_DEBUG and a category of LOGC_NONE.
  93
  94 The logging facilities are intended to replace DEBUG, but if DEBUG is defined
  95 at the top of a file, then it takes precedence. This means that debug()
  96 statements will result in output to the console and this output will not be
  97 logged.
  98
  99
 100 Logging destinations
 101 --------------------
 102
 103 If logging information goes nowhere then it serves no purpose. U-Boot provides
 104 several possible determinations for logging information, all of which can be
 105 enabled or disabled independently:
 106
 107    console - goes to stdout
 108
 109
 110 Log format
 111 ----------
 112
 113 You can control the log format using the 'log format' command. The basic
 114 format is:
 115
 116    LEVEL.category,file.c:123-func() message
 117
 118 In the above, file.c:123 is the filename where the log record was generated and
 119 func() is the function name. By default ('log format default') only the
 120 function name and message are displayed on the console. You can control which
 121 fields are present, but not the field order.
 122
 123
 124 Filters
 125 -------
 126
 127 Filters are attached to log drivers to control what those drivers emit. Only
 128 records that pass through the filter make it to the driver.
 129
 130 Filters can be based on several criteria:
 131
 132    - maximum log level
 133    - in a set of categories
 134    - in a set of files
 135
 136 If no filters are attached to a driver then a default filter is used, which
 137 limits output to records with a level less than CONFIG_LOG_MAX_LEVEL.
 138
 139
 140 Logging statements
 141 ------------------
 142
 143 The main logging function is:
 144
 145    log(category, level, format_string, ...)
 146
 147 Also debug() and error() will generate log records  - these use LOG_CATEGORY
 148 as the category, so you should #define this right at the top of the source
 149 file to ensure the category is correct.
 150
 151 You can also define CONFIG_LOG_ERROR_RETURN to enable the log_ret() macro. This
 152 can be used whenever your function returns an error value:
 153
 154    return log_ret(uclass_first_device(UCLASS_MMC, &dev));
 155
 156 This will write a log record when an error code is detected (a value < 0). This
 157 can make it easier to trace errors that are generated deep in the call stack.
 158
 159
 160 Code size
 161 ---------
 162
 163 Code size impact depends largely on what is enabled. The following numbers are
 164 for snow, which is a Thumb-2 board:
 165
 166 This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0
 167 CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0
 168 CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0
 169
 170 The last option turns every debug() statement into a logging call, which
 171 bloats the code hugely. The advantage is that it is then possible to enable
 172 all logging within U-Boot.
 173
 174
 175 To Do
 176 -----
 177
 178 There are lots of useful additions that could be made. None of the below is
 179 implemented! If you do one, please add a test in test/py/tests/test_log.py
 180
 181 Convenience functions to support setting the category:
 182
 183    log_arch(level, format_string, ...) - category LOGC_ARCH
 184    log_board(level, format_string, ...) - category LOGC_BOARD
 185    log_core(level, format_string, ...) - category LOGC_CORE
 186    log_dt(level, format_string, ...) - category LOGC_DT
 187
 188 Convenience functions to support a category defined for a single file, for
 189 example:
 190
 191    #define LOG_CATEGORY   UCLASS_USB
 192
 193 all of these can use LOG_CATEGORY as the category, and a log level
 194 corresponding to the function name:
 195
 196    logc(level, format_string, ...)
 197
 198 More logging destinations:
 199
 200    device - goes to a device (e.g. serial)
 201    buffer - recorded in a memory buffer
 202
 203 Convert debug() statements in the code to log() statements
 204
 205 Support making printf() emit log statements a L_INFO level
 206
 207 Convert error() statements in the code to log() statements
 208
 209 Figure out what to do with BUG(), BUG_ON() and warn_non_spl()
 210
 211 Figure out what to do with assert()
 212
 213 Add a way to browse log records
 214
 215 Add a way to record log records for browsing using an external tool
 216
 217 Add commands to add and remove filters
 218
 219 Add commands to add and remove log devices
 220
 221 Allow sharing of printf format strings in log records to reduce storage size
 222 for large numbers of log records
 223
 224 Add a command-line option to sandbox to set the default logging level
 225
 226 Convert core driver model code to use logging
 227
 228 Convert uclasses to use logging with the correct category
 229
 230 Consider making log() calls emit an automatic newline, perhaps with a logn()
 231    function to avoid that
 232
 233 Passing log records through to linux (e.g. via device tree /chosen)
 234
 235 Provide a command to access the number of log records generated, and the
 236 number dropped due to them being generated before the log system was ready.
 237
 238 Add a printf() format string pragma so that log statements are checked properly
 239
 240 Enhance the log console driver to show level / category / file / line
 241 information
 242
 243 Add a command to add new log records and delete existing records.
 244
 245 Provide additional log() functions - e.g. logc() to specify the category
 246
 247 --
 248 Simon Glass <sjg@chromium.org>
 249 15-Sep-17