u-boot/doc/README.trace

1 # SPDX-License-Identifier: GPL-2.0+
5 Tracing in U-Boot
8 U-Boot supports a simple tracing feature which allows a record of excecution
10 main use for this is to profile boot time.
14 --------
16 The trace feature uses GCC's instrument-functions feature to trace all
27 Quick-start using Sandbox
28 -------------------------
30 Sandbox is a build of U-Boot that can run under Linux so it is a convenient
43 Build sandbox U-Boot with tracing enabled:
48 Run sandbox, wait for a bit of trace information to appear, and then capture
51 $ ./sandbox/u-boot
54 U-Boot 2013.04-rc2-00100-ga72fcef (Apr 17 2013 - 19:25:24)
96 Then run proftool to convert the trace information to ftrace format.
98 $ ./sandbox/tools/proftool -m sandbox/System.map -p trace dump-ftrace >trace.txt
100 Finally run pytimechart to display it:
110 --------------
112 - CONFIG_TRACE
113 		Enables the trace feature in U-Boot.
115 - CONFIG_CMD_TRACE
118 - CONFIG_TRACE_BUFFER_SIZE
119 		Size of trace buffer to allocate for U-Boot. This buffer is
124 - CONFIG_TRACE_EARLY
127 - CONFIG_TRACE_EARLY_SIZE
128 		Size of 'early' trace buffer. Before U-Boot has relocated
135 - CONFIG_TRACE_EARLY_ADDR
139 Building U-Boot with Tracing Enabled
140 ------------------------------------
142 Pass 'FTRACE=1' to the U-Boot Makefile to actually instrument the code.
149 ---------------------
151 When you run U-Boot on your board it will collect trace data up to the
155 Collecting trace data has an affect on execution time/performance. You
156 will notice this particularly with trvial functions - the overhead of
157 recording their execution may even exceed their normal execution time.
160 doing end-to-end timing.
162 The best time to start tracing is right at the beginning of U-Boot. The
163 best time to stop tracing is right at the end. In practice it is hard
168 early architecture-specific init. However, it also misses the entire
171 U-Boot typically ends with a 'bootm' command which loads and runs an
175 the OS. In practical terms, U-Boot runs the 'fakegocmd' environment
190 --------
192 The trace command has variable sub-commands:
194 - stats
197 - pause
200 - resume
203 - funclist [<addr> <size>]
206 - calls  [<addr> <size>]
215 ---------------------
219 - profbase
222 - profoffset
225 - profsize
233 update profoffset each time. This allows successive commands to append data
242 - fakegocmd
243 		Specifies commands to run just before booting the OS. This
244 		is a useful time to write the trace data to the host for
249 ----------------------
261 TFTP. After this, U-Boot will boot the OS normally, albeit a little
266 ----------------------------
271 This tool must be given the U-Boot map file and the trace data received
272 from running that U-Boot. It produces a text output file.
275 	-m <map_file>
276 		Specify U-Boot map file
278 	-p <trace_file>
283 - dump-ftrace
288 ----------------------
290 You can use pytimechart for this (sudo apt-get pytimechart might work on
291 your Debian-style machine, and use your favourite search engine to obtain
293 has terse user interface but is very convenient for viewing U-Boot
298 --------------------
301 time:
304 you are helpful overall snapshot of the boot time.
306 2. Build U-Boot with tracing and run it. Note the difference in boot time
307 (it is common for tracing to add 10% to the time)
310 all the time is being spent.
316 5. Rebuild, run and collect again. Compare your results.
318 6. Keep going until you run out of steam, or your boot is fast enough.
322 -----------------
332 -----------
335 run-time configuration options for trace.
339 - Trace filter to select which functions are recorded
340 - Sample-based profiling using a timer interrupt
341 - Better control over trace depth
342 - Compression of trace information