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
16 --------
18 The trace feature uses GCC's instrument-functions feature to trace all
19 function entry/exit points. These are then recorded in a memory buffer.
20 The memory buffer can be saved to the host over a network link using
24 which extracts useful information from it. The resulting trace output
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
51 a trace:
53 $ ./sandbox/u-boot
56 U-Boot 2013.04-rc2-00100-ga72fcef (Apr 17 2013 - 19:25:24)
59 trace: enabled
65 =>trace stats
73 =>trace stats
81 =>trace calls 0 e00000
93 =>sb save host 0 trace 0 ${profoffset}
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
104 $ pytimechart trace.txt
106 Using this tool you can zoom and pan across the trace, with the function
112 --------------
114 - CONFIG_TRACE
115 		Enables the trace feature in U-Boot.
117 - CONFIG_CMD_TRACE
118 		Enables the trace command.
120 - CONFIG_TRACE_BUFFER_SIZE
121 		Size of trace buffer to allocate for U-Boot. This buffer is
123 		information. The address of the buffer is determined by
126 - CONFIG_TRACE_EARLY
129 - CONFIG_TRACE_EARLY_SIZE
130 		Size of 'early' trace buffer. Before U-Boot has relocated
131 		it doesn't have a proper trace buffer. On many boards
132 		you can define an area of memory to use for the trace
133 		buffer until the 'real' trace buffer is available after
134 		relocation. The contents of this buffer are then copied to
135 		the real buffer.
137 - CONFIG_TRACE_EARLY_ADDR
138 		Address of early trace buffer
141 Building U-Boot with Tracing Enabled
142 ------------------------------------
144 Pass 'FTRACE=1' to the U-Boot Makefile to actually instrument the code.
150 Collecting Trace Data
151 ---------------------
153 When you run U-Boot on your board it will collect trace data up to the
154 limit of the trace buffer size you have specified. Once that is exhausted
157 Collecting trace data has an affect on execution time/performance. You
158 will notice this particularly with trvial functions - the overhead of
162 doing end-to-end timing.
164 The best time to start tracing is right at the beginning of U-Boot. The
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
174 OS. There is useful trace data in the execution of that bootm
175 command. Therefore this implementation provides a way to collect trace
177 the OS. In practical terms, U-Boot runs the 'fakegocmd' environment
179 collects the trace data and writes it somewhere.
181 Trace data collection relies on a microsecond timer, accesed through
187 __attribute__((no_instrument_function)) so that the trace library can
192 --------
194 The trace command has variable sub-commands:
196 - stats
199 - pause
202 - resume
205 - funclist [<addr> <size>]
206 		Dump a list of functions into the buffer
208 - calls  [<addr> <size>]
209 		Dump function call trace into buffer
217 ---------------------
221 - profbase
222 		Base address of trace output buffer
224 - profoffset
225 		Offset of first unwritten byte in trace output buffer
227 - profsize
228 		Size of trace output buffer
230 All of these are set by the 'trace calls' command.
232 These variables keep track of the amount of data written to the trace
233 output buffer by the 'trace' command. The trace commands which write data
234 to the output buffer can use these to specify the buffer to write to, and
236 to the same buffer, for example:
238 	trace funclist 10000 e00000
239 	trace calls
241 (the latter command appends more data to the buffer).
244 - fakegocmd
246 		is a useful time to write the trace data to the host for
250 Writing Out Trace Data
251 ----------------------
253 Once the trace data is in an output buffer in memory there are various ways
257 fakegocmd=trace pause; usb start; set autoload n; bootp;
258 	trace calls 10000000 1000000;
262 a trace log to address 10000000 and sends it to a host machine using
263 TFTP. After this, U-Boot will boot the OS normally, albeit a little
267 Converting Trace Output Data
268 ----------------------------
270 The trace output data is kept in a binary format which is not documented
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>
281 		Specifiy profile/trace file
285 - dump-ftrace
289 Viewing the Trace Data
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
294 documentation). It expects the file to have a .txt extension. The program
295 has terse user interface but is very convenient for viewing U-Boot
300 --------------------
308 2. Build U-Boot with tracing and run it. Note the difference in boot time
311 3. Collect the trace information as descibed above. Use this to find where
323 Configuring Trace
324 -----------------
329 The maximum depth reached is recorded and displayed by the 'trace stats'
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