doc/develop/logging.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2 .. Copyright (c) 2017 Simon Glass <sjg@chromium.org>
   3
   4 Logging in U-Boot
   5 =================
   6
   7 Introduction
   8 ------------
   9
  10 U-Boot's internal operation involves many different steps and actions. From
  11 setting up the board to displaying a start-up screen to loading an Operating
  12 System, there are many component parts each with many actions.
  13
  14 Most of the time this internal detail is not useful. Displaying it on the
  15 console would delay booting (U-Boot's primary purpose) and confuse users.
  16
  17 But for digging into what is happening in a particular area, or for debugging
  18 a problem it is often useful to see what U-Boot is doing in more detail than
  19 is visible from the basic console output.
  20
  21 U-Boot's logging feature aims to satisfy this goal for both users and
  22 developers.
  23
  24
  25 Logging levels
  26 --------------
  27
  28 There are a number logging levels available, in increasing order of verbosity:
  29
  30 * LOGL_EMERG - Printed before U-Boot halts
  31 * LOGL_ALERT - Indicates action must be taken immediate or U-Boot will crash
  32 * LOGL_CRIT - Indicates a critical error that will cause boot failure
  33 * LOGL_ERR - Indicates an error that may cause boot failure
  34 * LOGL_WARNING - Warning about an unexpected condition
  35 * LOGL_NOTE - Important information about progress
  36 * LOGL_INFO - Information about normal boot progress
  37 * LOGL_DEBUG - Debug information (useful for debugging a driver or subsystem)
  38 * LOGL_DEBUG_CONTENT - Debug message showing full message content
  39 * LOGL_DEBUG_IO - Debug message showing hardware I/O access
  40
  41
  42 Logging category
  43 ----------------
  44
  45 Logging can come from a wide variety of places within U-Boot. Each log message
  46 has a category which is intended to allow messages to be filtered according to
  47 their source.
  48
  49 The following main categories are defined:
  50
  51 * LOGC_NONE - Unknown category (e.g. a debug() statement)
  52 * UCLASS\_... - Related to a particular uclass (e.g. UCLASS_USB)
  53 * LOGC_ARCH - Related to architecture-specific code
  54 * LOGC_BOARD - Related to board-specific code
  55 * LOGC_CORE - Related to core driver-model support
  56 * LOGC_DT - Related to device tree control
  57 * LOGC_EFI - Related to EFI implementation
  58
  59
  60 Enabling logging
  61 ----------------
  62
  63 The following options are used to enable logging at compile time:
  64
  65 * CONFIG_LOG - Enables the logging system
  66 * CONFIG_LOG_MAX_LEVEL - Max log level to build (anything higher is compiled
  67   out)
  68 * CONFIG_LOG_CONSOLE - Enable writing log records to the console
  69
  70 If CONFIG_LOG is not set, then no logging will be available.
  71
  72 The above have SPL and TPL versions also, e.g. CONFIG_SPL_LOG_MAX_LEVEL and
  73 CONFIG_TPL_LOG_MAX_LEVEL.
  74
  75
  76 Temporary logging within a single file
  77 --------------------------------------
  78
  79 Sometimes it is useful to turn on logging just in one file. You can use this
  80
  81 .. code-block:: c
  82
  83    #define LOG_DEBUG
  84
  85 to enable building in of all logging statements in a single file. Put it at
  86 the top of the file, before any #includes.
  87
  88 To actually get U-Boot to output this you need to also set the default logging
  89 level - e.g. set CONFIG_LOG_DEFAULT_LEVEL to 7 (LOGL_DEBUG) or more. Otherwise
  90 debug output is suppressed and will not be generated.
  91
  92
  93 Convenience functions
  94 ---------------------
  95
  96 A number of convenience functions are available to shorten the code needed
  97 for logging:
  98
  99 * log_err(_fmt...)
 100 * log_warning(_fmt...)
 101 * log_notice(_fmt...)
 102 * log_info(_fmt...)
 103 * log_debug(_fmt...)
 104 * log_content(_fmt...)
 105 * log_io(_fmt...)
 106
 107 With these the log level is implicit in the name. The category is set by
 108 LOG_CATEGORY, which you can only define once per file, above all #includes, e.g.
 109
 110 .. code-block:: c
 111
 112         #define LOG_CATEGORY LOGC_ALLOC
 113
 114 Remember that all uclasses IDs are log categories too.
 115
 116
 117 Log command
 118 -----------
 119
 120 The 'log' command provides access to several features:
 121
 122 * level - access the default log level
 123 * format - access the console log format
 124 * rec - output a log record
 125 * test - run tests
 126
 127 Type 'help log' for details.
 128
 129
 130 Using DEBUG
 131 -----------
 132
 133 U-Boot has traditionally used a #define called DEBUG to enable debugging on a
 134 file-by-file basis. The debug() macro compiles to a printf() statement if
 135 DEBUG is enabled, and an empty statement if not.
 136
 137 With logging enabled, debug() statements are interpreted as logging output
 138 with a level of LOGL_DEBUG and a category of LOGC_NONE.
 139
 140 The logging facilities are intended to replace DEBUG, but if DEBUG is defined
 141 at the top of a file, then it takes precedence. This means that debug()
 142 statements will result in output to the console and this output will not be
 143 logged.
 144
 145
 146 Logging destinations
 147 --------------------
 148
 149 If logging information goes nowhere then it serves no purpose. U-Boot provides
 150 several possible determinations for logging information, all of which can be
 151 enabled or disabled independently:
 152
 153 * console - goes to stdout
 154 * syslog - broadcast RFC 3164 messages to syslog servers on UDP port 514
 155
 156 The syslog driver sends the value of environmental variable 'log_hostname' as
 157 HOSTNAME if available.
 158
 159
 160 Log format
 161 ----------
 162
 163 You can control the log format using the 'log format' command. The basic
 164 format is::
 165
 166    LEVEL.category,file.c:123-func() message
 167
 168 In the above, file.c:123 is the filename where the log record was generated and
 169 func() is the function name. By default ('log format default') only the
 170 function name and message are displayed on the console. You can control which
 171 fields are present, but not the field order.
 172
 173
 174 Filters
 175 -------
 176
 177 Filters are attached to log drivers to control what those drivers emit. Only
 178 records that pass through the filter make it to the driver.
 179
 180 Filters can be based on several criteria:
 181
 182 * maximum log level
 183 * in a set of categories
 184 * in a set of files
 185
 186 If no filters are attached to a driver then a default filter is used, which
 187 limits output to records with a level less than CONFIG_MAX_LOG_LEVEL.
 188
 189
 190 Logging statements
 191 ------------------
 192
 193 The main logging function is:
 194
 195 .. code-block:: c
 196
 197    log(category, level, format_string, ...)
 198
 199 Also debug() and error() will generate log records  - these use LOG_CATEGORY
 200 as the category, so you should #define this right at the top of the source
 201 file to ensure the category is correct.
 202
 203 You can also define CONFIG_LOG_ERROR_RETURN to enable the log_ret() macro. This
 204 can be used whenever your function returns an error value:
 205
 206 .. code-block:: c
 207
 208    return log_ret(uclass_first_device(UCLASS_MMC, &dev));
 209
 210 This will write a log record when an error code is detected (a value < 0). This
 211 can make it easier to trace errors that are generated deep in the call stack.
 212
 213
 214 Code size
 215 ---------
 216
 217 Code size impact depends largely on what is enabled. The following numbers are
 218 generated by 'buildman -S' for snow, which is a Thumb-2 board (all units in
 219 bytes)::
 220
 221     This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0
 222     CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0
 223     CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0
 224
 225 The last option turns every debug() statement into a logging call, which
 226 bloats the code hugely. The advantage is that it is then possible to enable
 227 all logging within U-Boot.
 228
 229
 230 To Do
 231 -----
 232
 233 There are lots of useful additions that could be made. None of the below is
 234 implemented! If you do one, please add a test in test/py/tests/test_log.py
 235
 236 Convenience functions to support setting the category:
 237
 238 * log_arch(level, format_string, ...) - category LOGC_ARCH
 239 * log_board(level, format_string, ...) - category LOGC_BOARD
 240 * log_core(level, format_string, ...) - category LOGC_CORE
 241 * log_dt(level, format_string, ...) - category LOGC_DT
 242
 243 More logging destinations:
 244
 245 * device - goes to a device (e.g. serial)
 246 * buffer - recorded in a memory buffer
 247
 248 Convert debug() statements in the code to log() statements
 249
 250 Support making printf() emit log statements at L_INFO level
 251
 252 Convert error() statements in the code to log() statements
 253
 254 Figure out what to do with BUG(), BUG_ON() and warn_non_spl()
 255
 256 Figure out what to do with assert()
 257
 258 Add a way to browse log records
 259
 260 Add a way to record log records for browsing using an external tool
 261
 262 Add commands to add and remove filters
 263
 264 Add commands to add and remove log devices
 265
 266 Allow sharing of printf format strings in log records to reduce storage size
 267 for large numbers of log records
 268
 269 Add a command-line option to sandbox to set the default logging level
 270
 271 Convert core driver model code to use logging
 272
 273 Convert uclasses to use logging with the correct category
 274
 275 Consider making log() calls emit an automatic newline, perhaps with a logn()
 276 function to avoid that
 277
 278 Passing log records through to linux (e.g. via device tree /chosen)
 279
 280 Provide a command to access the number of log records generated, and the
 281 number dropped due to them being generated before the log system was ready.
 282
 283 Add a printf() format string pragma so that log statements are checked properly
 284
 285 Enhance the log console driver to show level / category / file / line
 286 information
 287
 288 Add a command to add new log records and delete existing records.
 289
 290 Provide additional log() functions - e.g. logc() to specify the category