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