xref: /aosp_15_r20/external/mesa3d/docs/u_trace.rst (revision 6104692788411f58d303aa86923a9ff6ecaded22)
1u_trace GPU Performance Tracing
2===============================
3
4Mesa has its own GPU performance tracing framework which drivers may
5choose to implement. ``gpu.renderstages.*`` producer for
6:doc:`Perfetto Tracing <perfetto>` is based on u_trace.
7
8It doesn't require external dependencies and much simpler to use. Though
9it provides information only about GPU timings and is harder to analyze
10for complex rendering.
11
12u_trace is useful when one needs to quickly identify performance bottleneck,
13or to build a tool to analyze the raw performance data.
14
15Drivers which support u_trace:
16   - Intel drivers: ANV, Iris
17   - Adreno drivers: Freedreno, Turnip
18
19Usage
20-----
21
22u_trace is controlled by environment variables:
23
24.. envvar:: MESA_GPU_TRACES
25
26   controls whether u_trace is enabled and trace output
27
28   ``print``
29      prints in a human readable text format. It should be noted that this
30      is mutually exclusive with ``print_json`` and both cannot be enabled
31      at the same time.
32   ``print_json``
33      prints in JSON format, suitable for parsing. Application should
34      appropriately finish its rendering in order for trace's json to be
35      valid. For the Vulkan API, it is expected to destroy the device,
36      for GL it's expected to destroy the context.
37   ``perfetto``
38      enables Perfetto instrumentation prior to connecting, Perfetto
39      traces can be collected without setting this but it may miss some
40      events prior to the tracing session being started.
41   ``markers``
42      enables marker instrumentation, will print trace markers into
43      the CS which can then be viewed by dumping the CS from the driver.
44
45         - For Turnip, ``cffdump`` can be used to view the markers in
46           the trace.
47   ``indirects``
48      enables indirect data capture for some of the tracepoints (like
49      indirect draw count or indirect dispatch size)
50
51.. envvar:: MESA_GPU_TRACEFILE
52
53   specifies a file where to write the output instead of ``stdout``
54
55.. envvar:: *_GPU_TRACEPOINT
56
57   tracepoints can be enabled or disabled using driver specific environment
58   variable. Most tracepoints are enabled by default. For instance
59   ``TU_GPU_TRACEPOINT=-blit,+render_pass`` will disable the
60   ``blit`` tracepoints and enable the ``render_pass`` tracepoints.
61
62   .. list-table::
63      :header-rows: 1
64
65      * - Driver
66        - Environment Variable
67        - Tracepoint Definitions
68      * - Freedreno
69        - .. envvar:: FD_GPU_TRACEPOINT
70        - ``src/gallium/drivers/freedreno/freedreno_tracepoints.py``
71      * - Turnip
72        - .. envvar:: TU_GPU_TRACEPOINT
73        - ``src/freedreno/vulkan/tu_tracepoints.py``
74      * - ANV
75        - .. envvar:: INTEL_GPU_TRACEPOINT
76        - ``src/intel/vulkan/intel_tracepoints.py``
77