docs: Add documentation regarding INTEL_MEASURE to envvars doc.

This was initially written by Mark Janes, and was part of MR 7354.

Reviewed-by: Kenneth Graunke <kenneth@whitecape.org>
Acked-by: Mike Blumenkrantz <michael.b.blumenkrantz@gmail.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/13043>

diff --git a/docs/envvars.rst b/docs/envvars.rst
index 6fac9a2..19267f7 100644 (file)
--- a/docs/envvars.rst
+++ b/docs/envvars.rst
@@ -335,6 +335,62 @@ Intel driver environment variables
    ``vs``
       dump shader assembly for vertex shaders
 
+:envvar:`INTEL_MEASURE`
+   Collects GPU timestamps over common intervals, and generates a CSV report
+   to show how long rendering took.  The overhead of collection is limited to
+   the flushing that is required at the interval boundaries for accurate
+   timestamps. By default, timing data is sent to ``stderr``.  To direct output
+   to a file:
+
+   ``INTEL_MEASURE=file=/tmp/measure.csv {workload}``
+
+   To begin capturing timestamps at a particular frame:
+
+   ``INTEL_MEASURE=file=/tmp/measure.csv,start=15 {workload}``
+
+   To capture only 23 frames:
+
+   ``INTEL_MEASURE=count=23 {workload}``
+
+   To capture frames 15-37, stopping before frame 38:
+
+   ``INTEL_MEASURE=start=15,count=23 {workload}``
+
+   Designate an asynchronous control file with:
+
+   ``INTEL_MEASURE=control=path/to/control.fifo {workload}``
+
+   As the workload runs, enable capture for 5 frames with:
+
+   ``$ echo 5 > path/to/control.fifo``
+
+   Enable unbounded capture:
+
+   ``$ echo -1 > path/to/control.fifo``
+
+   and disable with:
+
+   ``$ echo 0 > path/to/control.fifo``
+
+   Select the boundaries of each snapshot with:
+
+   ``INTEL_MEASURE=draw``
+      Collects timings for every render (DEFAULT)
+
+   ``INTEL_MEASURE=rt``
+      Collects timings when the render target changes
+
+   ``INTEL_MEASURE=batch``
+      Collects timings when batches are submitted
+
+   ``INTEL_MEASURE=frame``
+      Collects timings at frame boundaries
+
+   With ``INTEL_MEASURE=interval=5``, the duration of 5 events will be
+   combined into a single record in the output.  When possible, a single
+   start and end event will be submitted to the GPU to minimize
+   stalling.  Combined events will not span batches, except in
+   the case of ``INTEL_MEASURE=frame``.
 :envvar:`INTEL_NO_HW`
    if set to 1, true or yes, prevents batches from being submitted to the
    hardware. This is useful for debugging hangs, etc.