u-boot/doc/README.trace

4 # SPDX-License-Identifier:	GPL-2.0+
7 Tracing in U-Boot
10 U-Boot supports a simple tracing feature which allows a record of excecution
12 main use for this is to profile boot time.
16 --------
18 The trace feature uses GCC's instrument-functions feature to trace all
29 Quick-start using Sandbox
30 -------------------------
32 Sandbox is a build of U-Boot that can run under Linux so it is a convenient
45 Build sandbox U-Boot with tracing enabled:
50 Run sandbox, wait for a bit of trace information to appear, and then capture
53 $ ./sandbox/u-boot
56 U-Boot 2013.04-rc2-00100-ga72fcef (Apr 17 2013 - 19:25:24)
98 Then run proftool to convert the trace information to ftrace format.
100 $ ./sandbox/tools/proftool -m sandbox/System.map -p trace dump-ftrace >trace.txt
102 Finally run pytimechart to display it:
112 --------------
114 - CONFIG_TRACE
115 		Enables the trace feature in U-Boot.
117 - CONFIG_CMD_TRACE
120 - CONFIG_TRACE_BUFFER_SIZE
121 		Size of trace buffer to allocate for U-Boot. This buffer is
126 - CONFIG_TRACE_EARLY
129 - CONFIG_TRACE_EARLY_SIZE
130 		Size of 'early' trace buffer. Before U-Boot has relocated
137 - CONFIG_TRACE_EARLY_ADDR
141 Building U-Boot with Tracing Enabled
142 ------------------------------------
144 Pass 'FTRACE=1' to the U-Boot Makefile to actually instrument the code.
151 ---------------------
153 When you run U-Boot on your board it will collect trace data up to the
157 Collecting trace data has an affect on execution time/performance. You
158 will notice this particularly with trvial functions - the overhead of
159 recording their execution may even exceed their normal execution time.
162 doing end-to-end timing.
164 The best time to start tracing is right at the beginning of U-Boot. The
165 best time to stop tracing is right at the end. In practice it is hard
170 early architecture-specific init. However, it also misses the entire
173 U-Boot typically ends with a 'bootm' command which loads and runs an
177 the OS. In practical terms, U-Boot runs the 'fakegocmd' environment
192 --------
194 The trace command has variable sub-commands:
196 - stats
199 - pause
202 - resume
205 - funclist [<addr> <size>]
208 - calls  [<addr> <size>]
217 ---------------------
221 - profbase
224 - profoffset
227 - profsize
235 update profoffset each time. This allows successive commands to append data
244 - fakegocmd
245 		Specifies commands to run just before booting the OS. This
246 		is a useful time to write the trace data to the host for
251 ----------------------
263 TFTP. After this, U-Boot will boot the OS normally, albeit a little
268 ----------------------------
273 This tool must be given the U-Boot map file and the trace data received
274 from running that U-Boot. It produces a text output file.
277 	-m <map_file>
278 		Specify U-Boot map file
280 	-p <trace_file>
285 - dump-ftrace
290 ----------------------
292 You can use pytimechart for this (sudo apt-get pytimechart might work on
293 your Debian-style machine, and use your favourite search engine to obtain
295 has terse user interface but is very convenient for viewing U-Boot
300 --------------------
303 time:
306 you are helpful overall snapshot of the boot time.
308 2. Build U-Boot with tracing and run it. Note the difference in boot time
309 (it is common for tracing to add 10% to the time)
312 all the time is being spent.
318 5. Rebuild, run and collect again. Compare your results.
320 6. Keep going until you run out of steam, or your boot is fast enough.
324 -----------------
334 -----------
337 run-time configuration options for trace.
341 - Trace filter to select which functions are recorded
342 - Sample-based profiling using a timer interrupt
343 - Better control over trace depth
344 - Compression of trace information