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
14 --------
16 The trace feature uses GCC's instrument-functions feature to trace all
23 resembles that emitted by Linux's ftrace feature, so can be visually
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:
45 $ make FTRACE=1 O=sandbox sandbox_config
46 $ make FTRACE=1 O=sandbox
51 $ ./sandbox/u-boot
54 U-Boot 2013.04-rc2-00100-ga72fcef (Apr 17 2013 - 19:25:24)
80 Call list dumped to 00000000, size 0xae0a40
90 Environment size: 117/8188 bytes
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
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
152 limit of the trace buffer size you have specified. Once that is exhausted
156 will notice this particularly with trvial functions - the overhead of
160 doing end-to-end timing.
162 The best time to start tracing is right at the beginning of U-Boot. The
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>]
209 If the address and size are not given, these are obtained from environment
215 ---------------------
219 - profbase
222 - profoffset
225 - profsize
226 		Size of trace output buffer
242 - fakegocmd
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
284 	Write a text dump of the file in Linux ftrace format to stdout
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 --------------------
306 2. Build U-Boot with tracing and run it. Note the difference in boot time
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