AlexIndustrial/mesa
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Emma Anholt
2025-10-10 14:54:44 -07:00
committed by Marge Bot
parent 5ca03e1137
commit ed40f0e22a
1 changed files with 39 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/perfetto.rst
+39 -52
View File
@@ -58,40 +58,7 @@ 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>`__.
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``.
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:
.. code-block:: sh
cd subprojects/perfetto
CONFIG=<path/to/gpu.cfg> OUT=out/linux_clang_release ./tools/tmux -n
4. Start other producers you may need, e.g. ``pps-producer``.
5. Start ``perfetto`` under the tmux session initiated in step 3.
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``.
7. Go to `ui.perfetto.dev <https://ui.perfetto.dev>`__ and upload
``$HOME/Downloads/trace.protobuf`` by clicking on **Open trace file**.
8. Alternatively you can open the trace in `AGI <https://gpuinspector.dev/>`__
(which despite the name can be used to view non-android traces).
To be a bit more explicit, here is a listing of commands reproducing
the steps above :
1. Build Mesa with perfetto enabled.
.. code-block:: sh
@@ -100,21 +67,52 @@ the steps above :
# Build mesa
mesa $ meson compile -C build
2. Build Perfetto from sources available at ``subprojects/perfetto``.
.. code-block:: sh
# 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
# Start perfetto
perfetto $ CONFIG=../../src/tool/pps/cfg/system.cfg OUT=out/linux/ ./tools/tmux -n
# 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
# In parallel from the Mesa repo, start the PPS producer
mesa $ ./build/src/tool/pps/pps-producer
More build options can be found in `this guide <https://perfetto.dev/docs/quickstart/linux-tracing>`__.
# Back in the perfetto tmux, press enter to start the capture
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``.
4. Start the PPS producer to capture GPU performance counters.
.. 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
mesa $ meson devenv -C build vkcube
6. Capture a perfetto trace using ``tracebox``.
.. code-block:: sh
mesa $ sudo ./subprojects/perfetto/out/linux/tracebox --system-sockets --txt -c src/tool/pps/cfg/system.cfg -o vkcube.trace
7. Go to `ui.perfetto.dev <https://ui.perfetto.dev>`__ and upload
``vkcube.trace`` by clicking on **Open trace file**.
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
~~~~~~~~~~~~~~~~~~~~~