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