1.. SPDX-License-Identifier: GPL-2.0+:
2
3trace command
4=============
5
6Synopis
7-------
8
9::
10
11    trace stats
12    trace pause
13    trace resume
14    trace funclist [<addr> <size>]
15    trace calls [<addr> <size>]
16
17Description
18-----------
19
20The *trace* command is used to control the U-Boot tracing system. It allows
21tracing to be paused and resumed, shows statistics for traces and provides a
22way to dump out the trace information.
23
24
25trace stats
26~~~~~~~~~~~
27
28This display tracing statistics, as follows:
29
30function sites
31    Functions are binned as a way of reducing the amount of space needed to
32    hold all the function information. This is controlled by FUNC_SITE_SIZE in
33    the trace.h header file. The usual value is 4, which provides the finest
34    granularity (assuming a minimum instruction size of 4 bytes) which means
35    that every function can be resolved individually.
36
37function calls
38    Total number of function calls, including those which were not traced due
39    to buffer space. This count does not include functions which exceeded the
40    depth limit.
41
42untracked function calls
43    Total number of function calls which did not appear in the U-Boot image.
44    This can happen if a function is called outside the normal code area.
45
46traced function calls
47    Total number of function calls which were actually traced, i.e. are included
48    in the recorded trace data.
49
50dropped due to overflow
51    If the trace buffer was exhausted then this shows the number of records that
52    were dropped. Try reducing the depth limit or expanding the buffer size.
53
54maximum observed call depth
55    Maximum observed call depth while tracing.
56
57calls not traced due to depth
58    Counts the number of function calls that were not recorded because they
59    exceeded the maximum call depth.
60
61max function calls
62    Maximum number of function calls which can be recorded in the trace buffer,
63    given its size. Once `function calls` hits this value, recording stops.
64
65trace buffer
66    Address of trace buffer
67
68call records
69    Address of first trace record. This is near the start of the trace buffer,
70    after the function-call counts.
71
72
73trace pause
74~~~~~~~~~~~
75
76Pauses tracing, so that no more data is added to the trace buffer.
77
78
79trace resume
80~~~~~~~~~~~~
81
82Resumes tracing, so that new function calls are added to the trace buffer if
83there is sufficient space.
84
85
86trace funclist [<addr> <size>]
87~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
88
89Dumps a list of functions into the provided buffer. The file uses a format
90specific to U-Boot: a header, following by the function offset and call count.
91
92If the address and size are not given, these are obtained from
93:ref:`develop/trace:environment variables`. In any case the environment
94variables are updated after the command runs.
95
96The resulting data should be written out to the host, e.g. using Ethernet or
97a filesystem. There are no tools provided to read this sdata.
98
99
100trace calls [<addr> <size>]
101~~~~~~~~~~~~~~~~~~~~~~~~~~~
102
103Dumps a list of function calls into the provided buffer. The file uses a format
104specific to U-Boot: a header, following by the list of calls. The proftool
105tool can be used to convert this information ready for further analysis.
106
107
108Example
109-------
110
111::
112
113    => trace stats
114            269,252 function sites
115         38,025,059 function calls
116                  3 untracked function calls
117          7,382,690 traced function calls
118                 17 maximum observed call depth
119                 15 call depth limit
120         68,667,432 calls not traced due to depth
121         22,190,112 max function calls
122
123    trace buffer 6c000000 call records 6c20de78
124    => trace resume
125    => trace pause
126
127This shows that resuming the trace causes the buffer to overflow::
128
129    => trace stats
130            269,252 function sites
131         49,573,694 function calls
132                  3 untracked function calls
133         22,190,112 traced function calls (8289848 dropped due to overflow)
134                 17 maximum observed call depth
135                 15 call depth limit
136         68,667,432 calls not traced due to depth
137         22,190,112 max function calls
138
139    trace buffer 6c000000 call records 6c20de78
140    => trace funcs 30000000 0x100000
141    Function trace dumped to 30000000, size 0x1e70
142
143This shows collecting and writing out the result trace data:
144
145::
146    => trace calls 20000000 0x10000000
147    Call list dumped to 20000000, size 0xfdf21a0
148    => save mmc 1:1 20000000 /trace ${profoffset}
149    File System is consistent
150    file found, deleting
151    update journal finished
152    File System is consistent
153    update journal finished
154    266281376 bytes written in 18584 ms (13.7 MiB/s)
155
156From here you can use proftool to convert it:
157
158.. code-block:: bash
159
160    tools/proftool -m System.map -t trace -o asc.fg dump-ftrace
161
162
163.. _`ACPI specification`: https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf
164