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:`GPU_TRACE` 25 if set to ``1`` enables tracing and outputs the data into ``stdout`` 26 27:envvar:`GPU_TRACEFILE` 28 specifies a file where to write the output instead of ``stdout`` 29 30:envvar:`GPU_TRACE_FORMAT` 31 controls a format of the output 32 33 ``txt`` 34 human readable text format 35 ``json`` 36 json format, suitable for parsing. Application should appropriately 37 finish its rendering in order for trace's json to be valid. 38 For Vulkan api it is expected to destroy the device, for GL it is 39 expected to destroy the context. 40 41:envvar:`GPU_TRACE_INSTRUMENT` 42 Meaningful only for Perfetto tracing. If set to ``1`` enables 43 instrumentation of GPU commands before the tracing is enabled. 44 45:envvar:`*_GPU_TRACEPOINT` 46 tracepoints can be enabled or disabled using driver specific environment 47 variable. Most tracepoints are enabled by default. For instance 48 ``TU_GPU_TRACEPOINT=-blit,+render_pass`` will disable the 49 ``blit`` tracepoints and enable the ``render_pass`` tracepoints. 50 51.. list-table:: 52 :header-rows: 1 53 54 * - Driver 55 - Environment Variable 56 - Tracepoint Definitions 57 * - Freedreno 58 - :envvar:`FD_GPU_TRACEPOINT` 59 - ``src/gallium/drivers/freedreno/freedreno_tracepoints.py`` 60 * - Turnip 61 - :envvar:`TU_GPU_TRACEPOINT` 62 - ``src/freedreno/vulkan/tu_tracepoints.py`` 63