blob: 19856d43da22e8e59a3c48c008f0a2e61e9e7c37 [file] [log] [blame]
Simon Glass1d0f30a2017-12-04 13:48:31 -07001Logging 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
Heinrich Schuchardt1973b382018-01-22 20:10:45 +010054 LOGC_EFI - Related to EFI implementation
Simon Glass1d0f30a2017-12-04 13:48:31 -070055
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
Simon Glassf9811e82019-02-16 20:24:37 -070072Temporary 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
Simon Glass8dee7b92019-02-16 20:24:36 -070087Convenience 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
Simon Glass8cb7c042017-12-28 13:14:22 -0700113Log 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
Simon Glass1d0f30a2017-12-04 13:48:31 -0700126Using 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
Simon Glass8cb7c042017-12-28 13:14:22 -0700152Log 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
Simon Glass1d0f30a2017-12-04 13:48:31 -0700166Filters
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
Simon Glass3707c6e2017-12-28 13:14:23 -0700193You 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
Simon Glass1d0f30a2017-12-04 13:48:31 -0700201
202Code size
203---------
204
205Code size impact depends largely on what is enabled. The following numbers are
Simon Glassb71ac162018-04-02 02:42:53 -0600206generated by 'buildman -S' for snow, which is a Thumb-2 board (all units in
207bytes):
Simon Glass1d0f30a2017-12-04 13:48:31 -0700208
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
Simon Glass1d0f30a2017-12-04 13:48:31 -0700231More 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