Mesa (main): docs/panfrost: Document drm-shim usage

[GitLab Mirror]

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

Author: Alyssa Rosenzweig <alyssa at collabora.com>
Date:   Wed Apr 13 13:46:17 2022 -0400

docs/panfrost: Document drm-shim usage

Document how to build and use Panfrost's drm-shim implementation. I hope by
documenting this process, other Mesa developers are better able to test
Panfrost. In particular, this allows developers without Mali hardware to run
shader-db for any Mali target, which may be useful for debugging regressions
from common NIR changes.

drm-shim is not a substitute for testing against real hardware.

Special thanks to Emma Anholt and Icecream95 for building this infrastructure.

Signed-off-by: Alyssa Rosenzweig <alyssa at collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/15930>

---

 docs/drivers/panfrost.rst | 62 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/docs/drivers/panfrost.rst b/docs/drivers/panfrost.rst
index fcd3855cc06..daaad307dcd 100644
--- a/docs/drivers/panfrost.rst
+++ b/docs/drivers/panfrost.rst
@@ -55,6 +55,67 @@ Panfrost developers and users hang out on IRC at ``#panfrost`` on OFTC. Note
 that registering and authenticating with `NickServ` is required to prevent
 spam. `Join the chat. <https://webchat.oftc.net/?channels=#panfrost>`_
 
+drm-shim
+--------
+
+Panfrost implements ``drm-shim``, stubbing out the Panfrost kernel interface.
+Use cases for this functionality include:
+
+- Future hardware bring up
+- Running shader-db on non-Mali workstations
+- Reproducing compiler (and some driver) bugs without Mali hardware
+
+Although Mali hardware is usually paired with an Arm CPU, Panfrost is portable C
+code and should work on any Linux machine. In particular, you can test the
+compiler on shader-db on an Intel desktop.
+
+To build Mesa with Panfrost drm-shim, configure meson with
+``-Dgallium-drivers=panfrost`` and ``-Dtools=drm-shim``. See the above
+building section for a full invocation. The drm-shim binary will be built to
+``build/src/panfrost/drm-shim/libpanfrost_noop_drm_shim.so``.
+
+To use, set the ``LD_PRELOAD`` environment variable to the drm-shim binary.  It
+may also be necessary to set ``LIBGL_DRIVERS_PATH`` to the location where Mesa
+was installed.
+
+By default, drm-shim mocks a Mali-G52 system. To select a specific Mali GPU,
+set the ``PAN_GPU_ID`` environment variable to the desired GPU ID:
+
+=========  ============ =======
+Product    Architecture GPU ID
+=========  ============ =======
+Mali-T720  Midgard (v4) 720
+Mali-T860  Midgard (v5) 860
+Mali-G72   Bifrost (v6) 6221
+Mali-G52   Bifrost (v7) 7212
+=========  ============ =======
+
+Additional GPU IDs are enumerated in the ``panfrost_model_list`` list in
+``src/panfrost/lib/pan_props.c``.
+
+As an example: assuming Mesa is installed to a local path ``~/lib`` and Mesa's
+build directory is ``~/mesa/build``, a shader can be compiled for Mali-G52 as::
+
+   ~/shader-db$ BIFROST_MESA_DEBUG=shaders LIBGL_DRIVERS_PATH=~/lib/dri/ LD_PRELOAD=~/mesa/build/src/panfrost/drm-shim/libpanfrost_noop_drm_shim.so PAN_GPU_ID=7212 ./run shaders/glmark/1-1.shader_test
+
+The same shader can be compiled for Mali-T720 as::
+
+   ~/shader-db$ MIDGARD_MESA_DEBUG=shaders LIBGL_DRIVERS_PATH=~/lib/dri/ LD_PRELOAD=~/mesa/build/src/panfrost/drm-shim/libpanfrost_noop_drm_shim.so PAN_GPU_ID=720 ./run shaders/glmark/1-1.shader_test
+
+These examples set the compilers' ``shaders`` debug flags to dump the optimized
+NIR, backend IR after instruction selection, backend IR after register
+allocation and scheduling, and a disassembly of the final compiled binary.
+
+As another example, this invocation runs a single dEQP test "on" Mali-G52,
+pretty-printing GPU data structures and disassembling all shaders
+(``PAN_MESA_DEBUG=trace``) as well as dumping raw GPU memory
+(``PAN_MESA_DEBUG=dump``). The ``EGL_PLATFORM=surfaceless`` environment variable
+and various flags to dEQP mimic the surfaceless environment that our
+continuous integration (CI) uses. This eliminates window system dependencies,
+although it requires a specially built CTS::
+
+   ~/VK-GL-CTS/build/external/openglcts/modules$ PAN_MESA_DEBUG=trace,dump LIBGL_DRIVERS_PATH=~/lib/dri/ LD_PRELOAD=~/mesa/build/src/panfrost/drm-shim/libpanfrost_noop_drm_shim.so PAN_GPU_ID=7212 EGL_PLATFORM=surfaceless ./glcts --deqp-surface-type=pbuffer --deqp-gl-config-name=rgba8888d24s8ms0 --deqp-surface-width=256 --deqp-surface-height=256 -n dEQP-GLES31.functional.shaders.builtin_functions.common.abs.float_highp_compute
+
 U-interleaved tiling
 ---------------------
 
@@ -92,3 +153,4 @@ introduced the format with Utgard. It is the only tiling supported on Utgard. On
 Mali-T760 and newer, Arm Framebuffer Compression (AFBC) is more efficient and
 should be used instead where possible. However, not all formats are
 compressible, so u-interleaved tiling remains an important fallback on Panfrost.
+