docs/u_trace.rst

   1 u_trace GPU Performance Tracing
   2 ===============================
   3
   4 Mesa has its own GPU performance tracing framework which drivers may
   5 choose to implement. ``gpu.renderstages.*`` producer for
   6 :doc:`Perfetto Tracing <perfetto>` is based on u_trace.
   7
   8 It doesn't require external dependencies and much simpler to use. Though
   9 it provides information only about GPU timings and is harder to analyze
  10 for complex rendering.
  11
  12 u_trace is useful when one needs to quickly identify performance bottleneck,
  13 or to build a tool to analyze the raw performance data.
  14
  15 Drivers which support u_trace:
  16    - Intel drivers: ANV, Iris
  17    - Adreno drivers: Freedreno, Turnip
  18
  19 Usage
  20 -----
  21
  22 u_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``