Module: Mesa
Branch: main
Commit: 3ea0ec4697d7de7caf738edac72afd05ee434ad9
URL:    
http://cgit.freedesktop.org/mesa/mesa/commit/?id=3ea0ec4697d7de7caf738edac72afd05ee434ad9

Author: David Heidelberg <[email protected]>
Date:   Sat Jul  2 20:56:17 2022 +0200

docs/ci: show how to run traces locally

Newcomers may want to test traces locally and understand how the replay
works.

Acked-by: Guilherme Gallo <[email protected]>
Signed-off-by: David Heidelberg <[email protected]>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/17347>

---

 docs/ci/index.rst        |  5 +++++
 docs/ci/local-traces.rst | 45 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/docs/ci/index.rst b/docs/ci/index.rst
index 60339b04ecf..f3a0d7ca770 100644
--- a/docs/ci/index.rst
+++ b/docs/ci/index.rst
@@ -87,6 +87,11 @@ So the jobs are created in personal repositories, the name 
of the user's account
 to be added to the rules attribute of the Gitlab CI job that accesses the 
restricted
 accounts.
 
+.. toctree::
+   :maxdepth: 1
+
+   local-traces
+
 Intel CI
 --------
 
diff --git a/docs/ci/local-traces.rst b/docs/ci/local-traces.rst
new file mode 100644
index 00000000000..c13ddc51f2a
--- /dev/null
+++ b/docs/ci/local-traces.rst
@@ -0,0 +1,45 @@
+Running traces on a local machine
+=================================
+
+Prerequisites
+-------------
+- Install `Apitrace <https://apitrace.github.io/>`_
+- Install `Renderdoc <https://renderdoc.org/>`_ (only needed for some traces)
+- Download and compile `Piglit <https://gitlab.freedesktop.org/mesa/piglit>`_ 
and install his `dependencies 
<https://gitlab.freedesktop.org/mesa/piglit#2-setup>`_
+- Download traces you want to replay from `traces-db 
<https://gitlab.freedesktop.org/gfx-ci/tracie/traces-db/>`_
+
+Running single trace
+--------------------
+A simple run to see the output of the trace can be done with
+
+.. code-block:: console
+
+    apitrace replay -w name_of_trace.trace
+
+For more information, look into the `Apitrace documentation 
<https://github.com/apitrace/apitrace/blob/master/docs/USAGE.markdown>`_.
+
+For comparing checksums use:
+
+.. code-block:: console
+
+    cd piglit/replayer
+    export PIGLIT_SOURCE_DIR="../"
+    ./replayer.py compare trace -d test path/name_of_trace.trace 0 # replace 
with expected checksum
+
+
+Simulating CI trace job
+-----------------------
+
+Sometimes it's useful to be able to test traces on your local machine instead 
of the Mesa CI runner. To simulate the CI environment as closely as possible.
+
+Download the yml file from your driver's `ci/` directory and then change the 
path in the yml file from local proxy or MinIO to the local directory (url-like 
format ``file://``)
+
+.. code-block:: console
+
+    # The PIGLIT_REPLAY_DEVICE_NAME has to match name in the yml file.
+    export PIGLIT_REPLAY_DEVICE_NAME='your_device_name'
+    export PIGLIT_REPLAY_DESCRIPTION_FILE='path_to_mesa_traces_file.yml'
+    ./piglit run -l verbose --timeout 300 -j10 replay ~/results/
+
+
+Note: For replaying traces, you may need to allow higher GL and GLSL versions. 
You can achieve that by settingĀ  ``MESA_GLSL_VERSION_OVERRIDE`` and 
``MESA_GL_VERSION_OVERRIDE``.

Reply via email to