sync code with last improvements from OpenBSD

lib/mesa/docs/u_trace.rst

@@ -0,0 +1,62 @@
+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``