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
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:
51 $ ./sandbox/u-boot
54 U-Boot 2013.04-rc2-00100-ga72fcef (Apr 17 2013 - 19:25:24)
68 	     16 maximum observed call depth
69 	     15 call depth limit
70 	 66,491 calls not traced due to depth
76 	     16 maximum observed call depth
77 	     15 call depth limit
78       1,275,767 calls not traced due to depth
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
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
195 		Display tracing statistics
197 - pause
200 - resume
203 - funclist [<addr> <size>]
206 - calls  [<addr> <size>]
215 ---------------------
219 - profbase
222 - profoffset
225 - profsize
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
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 -----------------
325 There is a function call depth limit (set to 15 by default). When the
326 stack depth goes above this then no tracing information is recorded.
327 The maximum depth reached is recorded and displayed by the 'trace stats'
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