blob: f653fe7d79711945855a9c25b8e3ffa2ecf55898 [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
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