u_trace GPU Performance Tracing
===============================

Mesa has its own GPU performance tracing framework which drivers may
choose to implement. ``gpu.renderstages.*`` producer for
:doc:`Perfetto Tracing <perfetto>` is based on u_trace.

It doesn't require external dependencies and much simpler to use. Though
it provides information only about GPU timings and is harder to analyze
for complex rendering.

u_trace is useful when one needs to quickly identify performance bottleneck,
or to build a tool to analyze the raw performance data.

Drivers which support u_trace:
   - Intel drivers: ANV, Iris
   - Adreno drivers: Freedreno, Turnip

Usage
-----

u_trace is controlled by environment variables:

:envvar:`GPU_TRACE`
   if set to ``1`` enables tracing and outputs the data into ``stdout``

:envvar:`GPU_TRACEFILE`
   specifies a file where to write the output instead of ``stdout``

:envvar:`GPU_TRACE_FORMAT`
   controls a format of the output

   ``txt``
      human readable text format
   ``json``
      json format, suitable for parsing. Application should appropriately
      finish its rendering in order for trace's json to be valid.
      For Vulkan API it is expected to destroy the device, for GL it is
      expected to destroy the context.

:envvar:`GPU_TRACE_INSTRUMENT`
   Meaningful only for Perfetto tracing. If set to ``1`` enables
   instrumentation of GPU commands before the tracing is enabled.

:envvar:`*_GPU_TRACEPOINT`
   tracepoints can be enabled or disabled using driver specific environment
   variable. Most tracepoints are enabled by default. For instance
   ``TU_GPU_TRACEPOINT=-blit,+render_pass`` will disable the
   ``blit`` tracepoints and enable the ``render_pass`` tracepoints.

.. list-table::
   :header-rows: 1

   * - Driver
     - Environment Variable
     - Tracepoint Definitions
   * - Freedreno
     - :envvar:`FD_GPU_TRACEPOINT`
     - ``src/gallium/drivers/freedreno/freedreno_tracepoints.py``
   * - Turnip
     - :envvar:`TU_GPU_TRACEPOINT`
     - ``src/freedreno/vulkan/tu_tracepoints.py``