v3d: Introduce a DRM shim for calling out to the simulator.

The goal is to enable testing of parts of drivers without depending on any
particular kernel version or hardware being present.

Simply set LD_PRELOAD=$PREFIX/lib/libv3d_drm_shim.so in your environment,
and we'll fake a /dev/dri/renderD128 (or whatever the next available node
is) using v3dv3.  That node can then be used with the surfaceless or gbm
EGL platforms.

Acked-by: Iago Toral Quiroga <[email protected]>

1 files changed, 34 insertions, 0 deletions

diff --git a/src/drm-shim/README.md b/src/drm-shim/README.md
new file mode 100644
index 00000000000..031a4218229
--- /dev/null
+++ b/src/drm-shim/README.md
@@ -0,0 +1,34 @@
+# DRM shim - Fake GEM kernel drivers in userspace for CI
+
+On CI systems where we don't control the kernel, it would be nice to
+be able to present either no-op GEM devices (for shader-db runs) or
+simulator-backed GEM devices (for testing against a software simulator
+or FPGA).  This lets us do that by intercepting libc calls and
+exposing render nodes.
+
+## Limitations
+
+- Doesn't know how to handle DRM fds getting passed over the wire from
+  X11 (Could we use kmsro to support the X11 case?).
+- libc interception is rather glibc-specific and fragile.
+- Can easily break gdb if the libc interceptor code is what's broken.
+  (ulimit -c unlimited and doing gdb on the core after the fact can
+  help)
+
+## Using
+
+You choose the backend by setting `LD_PRELOAD` to the shim you want.
+Since this will effectively fake another DRM device to your system,
+you may need some work on your userspace to get your test application
+to use it if it's not the only DRM device present.  Setting
+`DRM_SHIM_DEBUG=1` in the environment will print out what path the
+shim initialized on.
+
+For piglit tests, you can set:
+
+```
+PIGLIT_PLATFORM=gbm
+WAFFLE_GBM_DEVICE=<path from DRM_SHIM_DEBUG>
+```
+
+See your drm-shim backend's README for details on how to use it.