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    LOGC_EFI     - Related to EFI implementation
  55
  56
  57 Enabling logging
  58 ----------------
  59
  60 The following options are used to enable logging at compile time:
  61
  62    CONFIG_LOG           - Enables the logging system
  63    CONFIG_LOG_MAX_LEVEL - Max log level to build (anything higher is compiled
  64                                 out)
  65    CONFIG_LOG_CONSOLE   - Enable writing log records to the console
  66
  67 If CONFIG_LOG is not set, then no logging will be available.
  68
  69 The above have SPL and TPL versions also, e.g. CONFIG_SPL_LOG_MAX_LEVEL and
  70 CONFIG_TPL_LOG_MAX_LEVEL.
  71
  72
  73 Temporary logging within a single file
  74 --------------------------------------
  75
  76 Sometimes it is useful to turn on logging just in one file. You can use this:
  77
  78    #define LOG_DEBUG
  79
  80 to enable building in of all logging statements in a single file. Put it at
  81 the top of the file, before any #includes.
  82
  83 To actually get U-Boot to output this you need to also set the default logging
  84 level - e.g. set CONFIG_LOG_DEFAULT_LEVEL to 7 (LOGL_DEBUG) or more. Otherwise
  85 debug output is suppressed and will not be generated.
  86
  87
  88 Convenience functions
  89 ---------------------
  90
  91 A number of convenience functions are available to shorten the code needed
  92 for logging:
  93
  94         log_err(_fmt...)
  95         log_warning(_fmt...)
  96         log_notice(_fmt...)
  97         log_info(_fmt...)
  98         log_debug(_fmt...)
  99         log_content(_fmt...)
 100         log_io(_fmt...)
 101
 102 With these the log level is implicit in the name. The category is set by
 103 LOG_CATEGORY, which you can only define once per file, above all #includes:
 104
 105         #define LOG_CATEGORY LOGC_ALLOC
 106
 107 or
 108
 109         #define LOG_CATEGORY UCLASS_SPI
 110
 111 Remember that all uclasses IDs are log categories too.
 112
 113
 114 Log commands
 115 ------------
 116
 117 The 'log' command provides access to several features:
 118
 119    level - access the default log level
 120    format - access the console log format
 121    rec - output a log record
 122    test - run tests
 123
 124 Type 'help log' for details.
 125
 126
 127 Using DEBUG
 128 -----------
 129
 130 U-Boot has traditionally used a #define called DEBUG to enable debugging on a
 131 file-by-file basis. The debug() macro compiles to a printf() statement if
 132 DEBUG is enabled, and an empty statement if not.
 133
 134 With logging enabled, debug() statements are interpreted as logging output
 135 with a level of LOGL_DEBUG and a category of LOGC_NONE.
 136
 137 The logging facilities are intended to replace DEBUG, but if DEBUG is defined
 138 at the top of a file, then it takes precedence. This means that debug()
 139 statements will result in output to the console and this output will not be
 140 logged.
 141
 142
 143 Logging destinations
 144 --------------------
 145
 146 If logging information goes nowhere then it serves no purpose. U-Boot provides
 147 several possible determinations for logging information, all of which can be
 148 enabled or disabled independently:
 149
 150    console - goes to stdout
 151    syslog - broadcast RFC 3164 messages to syslog servers on UDP port 514
 152
 153 The syslog driver sends the value of environmental variable 'log_hostname' as
 154 HOSTNAME if available.
 155
 156 Log format
 157 ----------
 158
 159 You can control the log format using the 'log format' command. The basic
 160 format is:
 161
 162    LEVEL.category,file.c:123-func() message
 163
 164 In the above, file.c:123 is the filename where the log record was generated and
 165 func() is the function name. By default ('log format default') only the
 166 function name and message are displayed on the console. You can control which
 167 fields are present, but not the field order.
 168
 169
 170 Filters
 171 -------
 172
 173 Filters are attached to log drivers to control what those drivers emit. Only
 174 records that pass through the filter make it to the driver.
 175
 176 Filters can be based on several criteria:
 177
 178    - maximum log level
 179    - in a set of categories
 180    - in a set of files
 181
 182 If no filters are attached to a driver then a default filter is used, which
 183 limits output to records with a level less than CONFIG_LOG_MAX_LEVEL.
 184
 185
 186 Logging statements
 187 ------------------
 188
 189 The main logging function is:
 190
 191    log(category, level, format_string, ...)
 192
 193 Also debug() and error() will generate log records  - these use LOG_CATEGORY
 194 as the category, so you should #define this right at the top of the source
 195 file to ensure the category is correct.
 196
 197 You can also define CONFIG_LOG_ERROR_RETURN to enable the log_ret() macro. This
 198 can be used whenever your function returns an error value:
 199
 200    return log_ret(uclass_first_device(UCLASS_MMC, &dev));
 201
 202 This will write a log record when an error code is detected (a value < 0). This
 203 can make it easier to trace errors that are generated deep in the call stack.
 204
 205
 206 Code size
 207 ---------
 208
 209 Code size impact depends largely on what is enabled. The following numbers are
 210 generated by 'buildman -S' for snow, which is a Thumb-2 board (all units in
 211 bytes):
 212
 213 This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0
 214 CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0
 215 CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0
 216
 217 The last option turns every debug() statement into a logging call, which
 218 bloats the code hugely. The advantage is that it is then possible to enable
 219 all logging within U-Boot.
 220
 221
 222 To Do
 223 -----
 224
 225 There are lots of useful additions that could be made. None of the below is
 226 implemented! If you do one, please add a test in test/py/tests/test_log.py
 227
 228 Convenience functions to support setting the category:
 229
 230    log_arch(level, format_string, ...) - category LOGC_ARCH
 231    log_board(level, format_string, ...) - category LOGC_BOARD
 232    log_core(level, format_string, ...) - category LOGC_CORE
 233    log_dt(level, format_string, ...) - category LOGC_DT
 234
 235 More logging destinations:
 236
 237    device - goes to a device (e.g. serial)
 238    buffer - recorded in a memory buffer
 239
 240 Convert debug() statements in the code to log() statements
 241
 242 Support making printf() emit log statements a L_INFO level
 243
 244 Convert error() statements in the code to log() statements
 245
 246 Figure out what to do with BUG(), BUG_ON() and warn_non_spl()
 247
 248 Figure out what to do with assert()
 249
 250 Add a way to browse log records
 251
 252 Add a way to record log records for browsing using an external tool
 253
 254 Add commands to add and remove filters
 255
 256 Add commands to add and remove log devices
 257
 258 Allow sharing of printf format strings in log records to reduce storage size
 259 for large numbers of log records
 260
 261 Add a command-line option to sandbox to set the default logging level
 262
 263 Convert core driver model code to use logging
 264
 265 Convert uclasses to use logging with the correct category
 266
 267 Consider making log() calls emit an automatic newline, perhaps with a logn()
 268    function to avoid that
 269
 270 Passing log records through to linux (e.g. via device tree /chosen)
 271
 272 Provide a command to access the number of log records generated, and the
 273 number dropped due to them being generated before the log system was ready.
 274
 275 Add a printf() format string pragma so that log statements are checked properly
 276
 277 Enhance the log console driver to show level / category / file / line
 278 information
 279
 280 Add a command to add new log records and delete existing records.
 281
 282 Provide additional log() functions - e.g. logc() to specify the category
 283
 284 --
 285 Simon Glass <sjg@chromium.org>
 286 15-Sep-17