Commit f68e5790 authored by Alyssa Rosenzweig's avatar Alyssa Rosenzweig
Browse files

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's avatarAlyssa Rosenzweig <>
Part-of: <mesa/mesa!15930>
parent 4d460c9f
Pipeline #561346 waiting for manual action with stages
in 3 minutes and 14 seconds
......@@ -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. <>`_
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
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
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/ 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/ 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/ 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.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment