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