blob: dc9e2deec50602e4f8d53bbd00a3ba7b33a30792 [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 Glass8cb7c042017-12-28 13:14:22 -070072Log commands
73------------
74
75The 'log' command provides access to several features:
76
77 level - access the default log level
78 format - access the console log format
79 rec - output a log record
80 test - run tests
81
82Type 'help log' for details.
83
84
Simon Glass1d0f30a2017-12-04 13:48:31 -070085Using DEBUG
86-----------
87
88U-Boot has traditionally used a #define called DEBUG to enable debugging on a
89file-by-file basis. The debug() macro compiles to a printf() statement if
90DEBUG is enabled, and an empty statement if not.
91
92With logging enabled, debug() statements are interpreted as logging output
93with a level of LOGL_DEBUG and a category of LOGC_NONE.
94
95The logging facilities are intended to replace DEBUG, but if DEBUG is defined
96at the top of a file, then it takes precedence. This means that debug()
97statements will result in output to the console and this output will not be
98logged.
99
100
101Logging destinations
102--------------------
103
104If logging information goes nowhere then it serves no purpose. U-Boot provides
105several possible determinations for logging information, all of which can be
106enabled or disabled independently:
107
108 console - goes to stdout
109
110
Simon Glass8cb7c042017-12-28 13:14:22 -0700111Log format
112----------
113
114You can control the log format using the 'log format' command. The basic
115format is:
116
117 LEVEL.category,file.c:123-func() message
118
119In the above, file.c:123 is the filename where the log record was generated and
120func() is the function name. By default ('log format default') only the
121function name and message are displayed on the console. You can control which
122fields are present, but not the field order.
123
124
Simon Glass1d0f30a2017-12-04 13:48:31 -0700125Filters
126-------
127
128Filters are attached to log drivers to control what those drivers emit. Only
129records that pass through the filter make it to the driver.
130
131Filters can be based on several criteria:
132
133 - maximum log level
134 - in a set of categories
135 - in a set of files
136
137If no filters are attached to a driver then a default filter is used, which
138limits output to records with a level less than CONFIG_LOG_MAX_LEVEL.
139
140
141Logging statements
142------------------
143
144The main logging function is:
145
146 log(category, level, format_string, ...)
147
148Also debug() and error() will generate log records - these use LOG_CATEGORY
149as the category, so you should #define this right at the top of the source
150file to ensure the category is correct.
151
Simon Glass3707c6e2017-12-28 13:14:23 -0700152You can also define CONFIG_LOG_ERROR_RETURN to enable the log_ret() macro. This
153can be used whenever your function returns an error value:
154
155 return log_ret(uclass_first_device(UCLASS_MMC, &dev));
156
157This will write a log record when an error code is detected (a value < 0). This
158can make it easier to trace errors that are generated deep in the call stack.
159
Simon Glass1d0f30a2017-12-04 13:48:31 -0700160
161Code size
162---------
163
164Code size impact depends largely on what is enabled. The following numbers are
165for snow, which is a Thumb-2 board:
166
167This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0
168CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0
169CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0
170
171The last option turns every debug() statement into a logging call, which
172bloats the code hugely. The advantage is that it is then possible to enable
173all logging within U-Boot.
174
175
176To Do
177-----
178
179There are lots of useful additions that could be made. None of the below is
180implemented! If you do one, please add a test in test/py/tests/test_log.py
181
182Convenience functions to support setting the category:
183
184 log_arch(level, format_string, ...) - category LOGC_ARCH
185 log_board(level, format_string, ...) - category LOGC_BOARD
186 log_core(level, format_string, ...) - category LOGC_CORE
187 log_dt(level, format_string, ...) - category LOGC_DT
188
189Convenience functions to support a category defined for a single file, for
190example:
191
192 #define LOG_CATEGORY UCLASS_USB
193
194all of these can use LOG_CATEGORY as the category, and a log level
195corresponding to the function name:
196
197 logc(level, format_string, ...)
198
199More logging destinations:
200
201 device - goes to a device (e.g. serial)
202 buffer - recorded in a memory buffer
203
204Convert debug() statements in the code to log() statements
205
206Support making printf() emit log statements a L_INFO level
207
208Convert error() statements in the code to log() statements
209
210Figure out what to do with BUG(), BUG_ON() and warn_non_spl()
211
212Figure out what to do with assert()
213
214Add a way to browse log records
215
216Add a way to record log records for browsing using an external tool
217
218Add commands to add and remove filters
219
220Add commands to add and remove log devices
221
222Allow sharing of printf format strings in log records to reduce storage size
223for large numbers of log records
224
225Add a command-line option to sandbox to set the default logging level
226
227Convert core driver model code to use logging
228
229Convert uclasses to use logging with the correct category
230
231Consider making log() calls emit an automatic newline, perhaps with a logn()
232 function to avoid that
233
234Passing log records through to linux (e.g. via device tree /chosen)
235
236Provide a command to access the number of log records generated, and the
237number dropped due to them being generated before the log system was ready.
238
239Add a printf() format string pragma so that log statements are checked properly
240
241Enhance the log console driver to show level / category / file / line
242information
243
244Add a command to add new log records and delete existing records.
245
246Provide additional log() functions - e.g. logc() to specify the category
247
248--
249Simon Glass <sjg@chromium.org>
25015-Sep-17