docs/u_trace: document u_trace usage

Signed-off-by: Danylo Piliaiev <dpiliaiev@igalia.com>
Reviewed-by: Lionel Landwerlin <lionel.g.landwerlin@intel.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/16579>

docs/gpu-perf-tracing.rst

@@ -0,0 +1,10 @@
+GPU Performance Tracing
+=======================
+
+TODO: Add general tips for performance measurement.
+
+.. toctree::
+   :maxdepth: 1
+
+   u_trace
+   perfetto

docs/index.rst

@@ -72,7 +72,7 @@ Linux, FreeBSD, and other operating systems.
    osmesa
    debugging
    perf
-   perfetto
+   gpu-perf-tracing
    extensions
    application-issues
    viewperf

docs/u_trace.rst

@@ -0,0 +1,43 @@
+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.