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