]>
Commit | Line | Data |
---|---|---|
1d0f30a8 SG |
1 | Logging in U-Boot |
2 | ================= | |
3 | ||
4 | Introduction | |
5 | ------------ | |
6 | ||
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. | |
10 | ||
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. | |
13 | ||
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. | |
17 | ||
18 | U-Boot's logging feature aims to satisfy this goal for both users and | |
19 | developers. | |
20 | ||
21 | ||
22 | Logging levels | |
23 | -------------- | |
24 | ||
25 | There 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 | ||
39 | Logging category | |
40 | ---------------- | |
41 | ||
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 | |
44 | their source. | |
45 | ||
46 | The 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 | ||
56 | Enabling logging | |
57 | ---------------- | |
58 | ||
59 | The 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 | ||
66 | If CONFIG_LOG is not set, then no logging will be available. | |
67 | ||
68 | The above have SPL versions also, e.g. CONFIG_SPL_MAX_LOG_LEVEL. | |
69 | ||
70 | ||
8cb7c042 SG |
71 | Log commands |
72 | ------------ | |
73 | ||
74 | The 'log' command provides access to several features: | |
75 | ||
76 | level - access the default log level | |
77 | format - access the console log format | |
78 | rec - output a log record | |
79 | test - run tests | |
80 | ||
81 | Type 'help log' for details. | |
82 | ||
83 | ||
1d0f30a8 SG |
84 | Using DEBUG |
85 | ----------- | |
86 | ||
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. | |
90 | ||
91 | With logging enabled, debug() statements are interpreted as logging output | |
92 | with a level of LOGL_DEBUG and a category of LOGC_NONE. | |
93 | ||
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 | |
97 | logged. | |
98 | ||
99 | ||
100 | Logging destinations | |
101 | -------------------- | |
102 | ||
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: | |
106 | ||
107 | console - goes to stdout | |
108 | ||
109 | ||
8cb7c042 SG |
110 | Log format |
111 | ---------- | |
112 | ||
113 | You can control the log format using the 'log format' command. The basic | |
114 | format is: | |
115 | ||
116 | LEVEL.category,file.c:123-func() message | |
117 | ||
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. | |
122 | ||
123 | ||
1d0f30a8 SG |
124 | Filters |
125 | ------- | |
126 | ||
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. | |
129 | ||
130 | Filters can be based on several criteria: | |
131 | ||
132 | - maximum log level | |
133 | - in a set of categories | |
134 | - in a set of files | |
135 | ||
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. | |
138 | ||
139 | ||
140 | Logging statements | |
141 | ------------------ | |
142 | ||
143 | The main logging function is: | |
144 | ||
145 | log(category, level, format_string, ...) | |
146 | ||
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. | |
150 | ||
151 | ||
152 | Code size | |
153 | --------- | |
154 | ||
155 | Code size impact depends largely on what is enabled. The following numbers are | |
156 | for snow, which is a Thumb-2 board: | |
157 | ||
158 | This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0 | |
159 | CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0 | |
160 | CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0 | |
161 | ||
162 | The last option turns every debug() statement into a logging call, which | |
163 | bloats the code hugely. The advantage is that it is then possible to enable | |
164 | all logging within U-Boot. | |
165 | ||
166 | ||
167 | To Do | |
168 | ----- | |
169 | ||
170 | There are lots of useful additions that could be made. None of the below is | |
171 | implemented! If you do one, please add a test in test/py/tests/test_log.py | |
172 | ||
173 | Convenience functions to support setting the category: | |
174 | ||
175 | log_arch(level, format_string, ...) - category LOGC_ARCH | |
176 | log_board(level, format_string, ...) - category LOGC_BOARD | |
177 | log_core(level, format_string, ...) - category LOGC_CORE | |
178 | log_dt(level, format_string, ...) - category LOGC_DT | |
179 | ||
180 | Convenience functions to support a category defined for a single file, for | |
181 | example: | |
182 | ||
183 | #define LOG_CATEGORY UCLASS_USB | |
184 | ||
185 | all of these can use LOG_CATEGORY as the category, and a log level | |
186 | corresponding to the function name: | |
187 | ||
188 | logc(level, format_string, ...) | |
189 | ||
190 | More logging destinations: | |
191 | ||
192 | device - goes to a device (e.g. serial) | |
193 | buffer - recorded in a memory buffer | |
194 | ||
195 | Convert debug() statements in the code to log() statements | |
196 | ||
197 | Support making printf() emit log statements a L_INFO level | |
198 | ||
199 | Convert error() statements in the code to log() statements | |
200 | ||
201 | Figure out what to do with BUG(), BUG_ON() and warn_non_spl() | |
202 | ||
203 | Figure out what to do with assert() | |
204 | ||
205 | Add a way to browse log records | |
206 | ||
207 | Add a way to record log records for browsing using an external tool | |
208 | ||
209 | Add commands to add and remove filters | |
210 | ||
211 | Add commands to add and remove log devices | |
212 | ||
213 | Allow sharing of printf format strings in log records to reduce storage size | |
214 | for large numbers of log records | |
215 | ||
216 | Add a command-line option to sandbox to set the default logging level | |
217 | ||
218 | Convert core driver model code to use logging | |
219 | ||
220 | Convert uclasses to use logging with the correct category | |
221 | ||
222 | Consider making log() calls emit an automatic newline, perhaps with a logn() | |
223 | function to avoid that | |
224 | ||
225 | Passing log records through to linux (e.g. via device tree /chosen) | |
226 | ||
227 | Provide a command to access the number of log records generated, and the | |
228 | number dropped due to them being generated before the log system was ready. | |
229 | ||
230 | Add a printf() format string pragma so that log statements are checked properly | |
231 | ||
232 | Enhance the log console driver to show level / category / file / line | |
233 | information | |
234 | ||
235 | Add a command to add new log records and delete existing records. | |
236 | ||
237 | Provide additional log() functions - e.g. logc() to specify the category | |
238 | ||
239 | -- | |
240 | Simon Glass <sjg@chromium.org> | |
241 | 15-Sep-17 |