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.
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.
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.
18 U-Boot's logging feature aims to satisfy this goal for both users and
25 There are a number logging levels available, in increasing order of verbosity:
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
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
46 The following main categories are defined:
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
59 The following options are used to enable logging at compile time:
61 CONFIG_LOG - Enables the logging system
62 CONFIG_MAX_LOG_LEVEL - Max log level to build (anything higher is compiled
64 CONFIG_LOG_CONSOLE - Enable writing log records to the console
66 If CONFIG_LOG is not set, then no logging will be available.
68 The above have SPL versions also, e.g. CONFIG_SPL_MAX_LOG_LEVEL.
74 The 'log' command provides access to several features:
76 level - access the default log level
77 format - access the console log format
78 rec - output a log record
81 Type 'help log' for details.
87 U-Boot has traditionally used a #define called DEBUG to enable debugging on a
88 file-by-file basis. The debug() macro compiles to a printf() statement if
89 DEBUG is enabled, and an empty statement if not.
91 With logging enabled, debug() statements are interpreted as logging output
92 with a level of LOGL_DEBUG and a category of LOGC_NONE.
94 The logging facilities are intended to replace DEBUG, but if DEBUG is defined
95 at the top of a file, then it takes precedence. This means that debug()
96 statements will result in output to the console and this output will not be
103 If logging information goes nowhere then it serves no purpose. U-Boot provides
104 several possible determinations for logging information, all of which can be
105 enabled or disabled independently:
107 console - goes to stdout
113 You can control the log format using the 'log format' command. The basic
116 LEVEL.category,file.c:123-func() message
118 In the above, file.c:123 is the filename where the log record was generated and
119 func() is the function name. By default ('log format default') only the
120 function name and message are displayed on the console. You can control which
121 fields are present, but not the field order.
127 Filters are attached to log drivers to control what those drivers emit. Only
128 records that pass through the filter make it to the driver.
130 Filters can be based on several criteria:
133 - in a set of categories
136 If no filters are attached to a driver then a default filter is used, which
137 limits output to records with a level less than CONFIG_LOG_MAX_LEVEL.
143 The main logging function is:
145 log(category, level, format_string, ...)
147 Also debug() and error() will generate log records - these use LOG_CATEGORY
148 as the category, so you should #define this right at the top of the source
149 file to ensure the category is correct.
151 You can also define CONFIG_LOG_ERROR_RETURN to enable the log_ret() macro. This
152 can be used whenever your function returns an error value:
154 return log_ret(uclass_first_device(UCLASS_MMC, &dev));
156 This will write a log record when an error code is detected (a value < 0). This
157 can make it easier to trace errors that are generated deep in the call stack.
163 Code size impact depends largely on what is enabled. The following numbers are
164 for snow, which is a Thumb-2 board:
166 This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0
167 CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0
168 CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0
170 The last option turns every debug() statement into a logging call, which
171 bloats the code hugely. The advantage is that it is then possible to enable
172 all logging within U-Boot.
178 There are lots of useful additions that could be made. None of the below is
179 implemented! If you do one, please add a test in test/py/tests/test_log.py
181 Convenience functions to support setting the category:
183 log_arch(level, format_string, ...) - category LOGC_ARCH
184 log_board(level, format_string, ...) - category LOGC_BOARD
185 log_core(level, format_string, ...) - category LOGC_CORE
186 log_dt(level, format_string, ...) - category LOGC_DT
188 Convenience functions to support a category defined for a single file, for
191 #define LOG_CATEGORY UCLASS_USB
193 all of these can use LOG_CATEGORY as the category, and a log level
194 corresponding to the function name:
196 logc(level, format_string, ...)
198 More logging destinations:
200 device - goes to a device (e.g. serial)
201 buffer - recorded in a memory buffer
203 Convert debug() statements in the code to log() statements
205 Support making printf() emit log statements a L_INFO level
207 Convert error() statements in the code to log() statements
209 Figure out what to do with BUG(), BUG_ON() and warn_non_spl()
211 Figure out what to do with assert()
213 Add a way to browse log records
215 Add a way to record log records for browsing using an external tool
217 Add commands to add and remove filters
219 Add commands to add and remove log devices
221 Allow sharing of printf format strings in log records to reduce storage size
222 for large numbers of log records
224 Add a command-line option to sandbox to set the default logging level
226 Convert core driver model code to use logging
228 Convert uclasses to use logging with the correct category
230 Consider making log() calls emit an automatic newline, perhaps with a logn()
231 function to avoid that
233 Passing log records through to linux (e.g. via device tree /chosen)
235 Provide a command to access the number of log records generated, and the
236 number dropped due to them being generated before the log system was ready.
238 Add a printf() format string pragma so that log statements are checked properly
240 Enhance the log console driver to show level / category / file / line
243 Add a command to add new log records and delete existing records.
245 Provide additional log() functions - e.g. logc() to specify the category
248 Simon Glass <sjg@chromium.org>