docs/perfetto: Explain using tracebox, and put commands in the list.

This binary that perfetto builds automatically launches traced and
traced_probes, doesn't need tmux installed, doesn't need you to know tmux
ui, and doesn't need the tmux helper script hacked to not call the wrong
arch's ninja if you cross compiled.

Also, it's silly to send people into an explanation and links to docs,
when we have the instructions they actually want below.

Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/37826>

1 files changed, 38 insertions, 51 deletions

diff --git a/docs/perfetto.rst b/docs/perfetto.rst
index 35f5056ae53..b7778e6241f 100644
--- a/docs/perfetto.rst
+++ b/docs/perfetto.rst
@@ -58,63 +58,61 @@ Run
 
 To capture a trace with Perfetto you need to take the following steps:
 
-1. Build Perfetto from sources available at ``subprojects/perfetto`` following
-   `this guide <https://perfetto.dev/docs/quickstart/linux-tracing>`__.
+1. Build Mesa with perfetto enabled.
 
-2. Select a `trace config <https://perfetto.dev/docs/concepts/config>`__, likely
-   ``src/tool/pps/cfg/system.cfg`` which does whole-system including GPU
-   profiling for any supported GPUs).  Other configs are available in that
-   directory for CPU-only or GPU-only tracing, and more examples of config files
-   can be found in ``subprojects/perfetto/test/configs``.
+.. code-block:: sh
 
-3. Change directory to ``subprojects/perfetto`` and run a
-   `convenience script <https://perfetto.dev/docs/getting-started/system-tracing#recording-your-first-system-trace>`__
-   to start the tracing service:
+   # Configure Mesa with perfetto
+   mesa $ meson . build -Dperfetto=true -Dvulkan-drivers=intel,broadcom -Dgallium-drivers=
+   # Build mesa
+   mesa $ meson compile -C build
 
-   .. code-block:: sh
+2. Build Perfetto from sources available at ``subprojects/perfetto``.
 
-      cd subprojects/perfetto
-      CONFIG=<path/to/gpu.cfg> OUT=out/linux_clang_release ./tools/tmux -n
+.. code-block:: sh
 
-4. Start other producers you may need, e.g. ``pps-producer``.
+   # Within the Mesa repo, build perfetto
+   mesa $ cd subprojects/perfetto
+   perfetto $ ./tools/install-build-deps
+   perfetto $ ./tools/gn gen --args='is_debug=false' out/linux
+   perfetto $ ./tools/ninja -C out/linux
 
-5. Start ``perfetto`` under the tmux session initiated in step 3.
+   # Example arm64 cross compile instead
+   perfetto $ ./tools/install-build-deps --linux-arm
+   perfetto $ ./tools/gn gen --args='is_debug=false target_cpu="arm64"' out/linux-arm64
 
-6. Once tracing has finished, you can detach from tmux with :kbd:`Ctrl+b`,
-   :kbd:`d`, and the convenience script should automatically copy the trace
-   files into ``$HOME/Downloads``.
+More build options can be found in `this guide <https://perfetto.dev/docs/quickstart/linux-tracing>`__.
 
-7. Go to `ui.perfetto.dev <https://ui.perfetto.dev>`__ and upload
-   ``$HOME/Downloads/trace.protobuf`` by clicking on **Open trace file**.
+3. Select a `trace config <https://perfetto.dev/docs/concepts/config>`__, likely
+   ``src/tool/pps/cfg/system.cfg`` which does whole-system including GPU
+   profiling for any supported GPUs).  Other configs are available in that
+   directory for CPU-only or GPU-only tracing, and more examples of config files
+   can be found in ``subprojects/perfetto/test/configs``.
 
-8. Alternatively you can open the trace in `AGI <https://gpuinspector.dev/>`__
-   (which despite the name can be used to view non-android traces).
+4. Start the PPS producer to capture GPU performance counters.
 
-To be a bit more explicit, here is a listing of commands reproducing
-the steps above :
+.. code-block:: sh
+
+   mesa $ sudo meson devenv -C build pps-producer
+
+5. Start your application (and any other GPU-using system components) you want
+   to trace using the perfetto-enabled Mesa build.
 
 .. code-block:: sh
 
-   # Configure Mesa with perfetto
-   mesa $ meson . build -Dperfetto=true -Dvulkan-drivers=intel,broadcom -Dgallium-drivers=
-   # Build mesa
-   mesa $ meson compile -C build
+   mesa $ meson devenv -C build vkcube
 
-   # Within the Mesa repo, build perfetto
-   mesa $ cd subprojects/perfetto
-   perfetto $ ./tools/install-build-deps
-   perfetto $ ./tools/gn gen --args='is_debug=false' out/linux
-   # Example arm64 cross compile instead
-   # perfetto $ ./tools/gn gen --args='is_debug=false target_cpu="arm64"' out/linux-arm64
-   perfetto $ ./tools/ninja -C out/linux
+6. Capture a perfetto trace using ``tracebox``.
+
+.. code-block:: sh
 
-   # Start perfetto
-   perfetto $ CONFIG=../../src/tool/pps/cfg/system.cfg OUT=out/linux/ ./tools/tmux -n
+   mesa $ sudo ./subprojects/perfetto/out/linux/tracebox --system-sockets --txt -c src/tool/pps/cfg/system.cfg -o vkcube.trace
 
-   # In parallel from the Mesa repo, start the PPS producer
-   mesa $ ./build/src/tool/pps/pps-producer
+7.  Go to `ui.perfetto.dev <https://ui.perfetto.dev>`__ and upload
+    ``vkcube.trace`` by clicking on **Open trace file**.
 
-   # Back in the perfetto tmux, press enter to start the capture
+8.  Alternatively you can open the trace in `AGI <https://gpuinspector.dev/>`__
+    (which despite the name can be used to view non-android traces).
 
 CPU Tracing
 ~~~~~~~~~~~
@@ -233,17 +231,6 @@ for pps_producer using the environment variable ``V3D_DS_COUNTER``.
 Troubleshooting
 ---------------
 
-Tmux
-~~~~
-
-If the convenience script ``tools/tmux`` keeps copying artifacts to your
-``SSH_TARGET`` without starting the tmux session, make sure you have ``tmux``
-installed in your system.
-
-.. code-block:: sh
-
-   apt install tmux
-
 Missing counter names
 ~~~~~~~~~~~~~~~~~~~~~