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 55 56Enabling logging 57---------------- 58 59The 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 66If CONFIG_LOG is not set, then no logging will be available. 67 68The above have SPL versions also, e.g. CONFIG_SPL_MAX_LOG_LEVEL. 69 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 86 87Logging destinations 88-------------------- 89 90If logging information goes nowhere then it serves no purpose. U-Boot provides 91several possible determinations for logging information, all of which can be 92enabled or disabled independently: 93 94 console - goes to stdout 95 96 97Filters 98------- 99 100Filters are attached to log drivers to control what those drivers emit. Only 101records that pass through the filter make it to the driver. 102 103Filters can be based on several criteria: 104 105 - maximum log level 106 - in a set of categories 107 - in a set of files 108 109If no filters are attached to a driver then a default filter is used, which 110limits output to records with a level less than CONFIG_LOG_MAX_LEVEL. 111 112 113Logging statements 114------------------ 115 116The main logging function is: 117 118 log(category, level, format_string, ...) 119 120Also debug() and error() will generate log records - these use LOG_CATEGORY 121as the category, so you should #define this right at the top of the source 122file to ensure the category is correct. 123 124 125Code size 126--------- 127 128Code size impact depends largely on what is enabled. The following numbers are 129for snow, which is a Thumb-2 board: 130 131This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0 132CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0 133CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0 134 135The last option turns every debug() statement into a logging call, which 136bloats the code hugely. The advantage is that it is then possible to enable 137all logging within U-Boot. 138 139 140To Do 141----- 142 143There are lots of useful additions that could be made. None of the below is 144implemented! If you do one, please add a test in test/py/tests/test_log.py 145 146Convenience functions to support setting the category: 147 148 log_arch(level, format_string, ...) - category LOGC_ARCH 149 log_board(level, format_string, ...) - category LOGC_BOARD 150 log_core(level, format_string, ...) - category LOGC_CORE 151 log_dt(level, format_string, ...) - category LOGC_DT 152 153Convenience functions to support a category defined for a single file, for 154example: 155 156 #define LOG_CATEGORY UCLASS_USB 157 158all of these can use LOG_CATEGORY as the category, and a log level 159corresponding to the function name: 160 161 logc(level, format_string, ...) 162 163More logging destinations: 164 165 device - goes to a device (e.g. serial) 166 buffer - recorded in a memory buffer 167 168Convert debug() statements in the code to log() statements 169 170Support making printf() emit log statements a L_INFO level 171 172Convert error() statements in the code to log() statements 173 174Figure out what to do with BUG(), BUG_ON() and warn_non_spl() 175 176Figure out what to do with assert() 177 178Add a way to browse log records 179 180Add a way to record log records for browsing using an external tool 181 182Add commands to add and remove filters 183 184Add commands to add and remove log devices 185 186Allow sharing of printf format strings in log records to reduce storage size 187for large numbers of log records 188 189Add a command-line option to sandbox to set the default logging level 190 191Convert core driver model code to use logging 192 193Convert uclasses to use logging with the correct category 194 195Consider making log() calls emit an automatic newline, perhaps with a logn() 196 function to avoid that 197 198Passing log records through to linux (e.g. via device tree /chosen) 199 200Provide a command to access the number of log records generated, and the 201number dropped due to them being generated before the log system was ready. 202 203Add a printf() format string pragma so that log statements are checked properly 204 205Enhance the log console driver to show level / category / file / line 206information 207 208Add a command to add new log records and delete existing records. 209 210Provide additional log() functions - e.g. logc() to specify the category 211 212-- 213Simon Glass <sjg@chromium.org> 21415-Sep-17 215