diff options
Diffstat (limited to 'doc/usage/cmd/trace.rst')
| -rw-r--r-- | doc/usage/cmd/trace.rst | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/doc/usage/cmd/trace.rst b/doc/usage/cmd/trace.rst new file mode 100644 index 0000000000..3bdf4f0a86 --- /dev/null +++ b/doc/usage/cmd/trace.rst @@ -0,0 +1,163 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +trace command +============= + +Synopis +------- + +:: + + trace stats + trace pause + trace resume + trace funclist [<addr> <size>] + trace calls [<addr> <size>] + +Description +----------- + +The *trace* command is used to control the U-Boot tracing system. It allows +tracing to be paused and resumed, shows statistics for traces and provides a +way to dump out the trace information. + + +trace stats +~~~~~~~~~~~ + +This display tracing statistics, as follows: + +function sites + Functions are binned as a way of reducing the amount of space needed to + hold all the function information. This is controlled by FUNC_SITE_SIZE in + the trace.h header file. The usual value is 4, which provides the finest + granularity (assuming a minimum instruction size of 4 bytes) which means + that every function can be resolved individually. + +function calls + Total number of function calls, including those which were not traced due + to buffer space. This count does not include functions which exceeded the + depth limit. + +untracked function calls + Total number of function calls which did not appear in the U-Boot image. + This can happen if a function is called outside the normal code area. + +traced function calls + Total number of function calls which were actually traced, i.e. are included + in the recorded trace data. + +dropped due to overflow + If the trace buffer was exhausted then this shows the number of records that + were dropped. Try reducing the depth limit or expanding the buffer size. + +maximum observed call depth + Maximum observed call depth while tracing. + +calls not traced due to depth + Counts the number of function calls that were not recorded because they + exceeded the maximum call depth. + +max function calls + Maximum number of function calls which can be recorded in the trace buffer, + given its size. Once `function calls` hits this value, recording stops. + +trace buffer + Address of trace buffer + +call records + Address of first trace record. This is near the start of the trace buffer, + after the function-call counts. + + +trace pause +~~~~~~~~~~~ + +Pauses tracing, so that no more data is added to the trace buffer. + + +trace resume +~~~~~~~~~~~~ + +Resumes tracing, so that new function calls are added to the trace buffer if +there is sufficient space. + + +trace funclist [<addr> <size>] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Dumps a list of functions into the provided buffer. The file uses a format +specific to U-Boot: a header, following by the function offset and call count. + +If the address and size are not given, these are obtained from +:ref:`develop/trace:environment variables`. In any case the environment +variables are updated after the command runs. + +The resulting data should be written out to the host, e.g. using Ethernet or +a filesystem. There are no tools provided to read this sdata. + + +trace calls [<addr> <size>] +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Dumps a list of function calls into the provided buffer. The file uses a format +specific to U-Boot: a header, following by the list of calls. The proftool +tool can be used to convert this information ready for further analysis. + + +Example +------- + +:: + + => trace stats + 269,252 function sites + 38,025,059 function calls + 3 untracked function calls + 7,382,690 traced function calls + 17 maximum observed call depth + 15 call depth limit + 68,667,432 calls not traced due to depth + 22,190,112 max function calls + + trace buffer 6c000000 call records 6c20de78 + => trace resume + => trace pause + +This shows that resuming the trace causes the buffer to overflow:: + + => trace stats + 269,252 function sites + 49,573,694 function calls + 3 untracked function calls + 22,190,112 traced function calls (8289848 dropped due to overflow) + 17 maximum observed call depth + 15 call depth limit + 68,667,432 calls not traced due to depth + 22,190,112 max function calls + + trace buffer 6c000000 call records 6c20de78 + => trace funcs 30000000 0x100000 + Function trace dumped to 30000000, size 0x1e70 + +This shows collecting and writing out the result trace data: + +:: + => trace calls 20000000 0x10000000 + Call list dumped to 20000000, size 0xfdf21a0 + => save mmc 1:1 20000000 /trace ${profoffset} + File System is consistent + file found, deleting + update journal finished + File System is consistent + update journal finished + 266281376 bytes written in 18584 ms (13.7 MiB/s) + +From here you can use proftool to convert it: + +.. code-block:: bash + + tools/proftool -m System.map -t trace -o asc.fg dump-ftrace + + +.. _`ACPI specification`: https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf |