1# DRM shim - Fake GEM kernel drivers in userspace for CI
2
3On CI systems where we don't control the kernel, it would be nice to
4be able to present either no-op GEM devices (for shader-db runs) or
5simulator-backed GEM devices (for testing against a software simulator
6or FPGA).  This lets us do that by intercepting libc calls and
7exposing render nodes.
8
9## Limitations
10
11- Doesn't know how to handle DRM fds getting passed over the wire from
12  X11 (Could we use kmsro to support the X11 case?).
13- libc interception is rather glibc-specific and fragile.
14- Can easily break gdb if the libc interceptor code is what's broken.
15  (ulimit -c unlimited and doing gdb on the core after the fact can
16  help)
17
18## Using
19
20You choose the backend by setting `LD_PRELOAD` to the shim you want.
21Since this will effectively fake another DRM device to your system,
22you may need some work on your userspace to get your test application
23to use it if it's not the only DRM device present.  Setting
24`DRM_SHIM_DEBUG=1` in the environment will print out what path the
25shim initialized on.
26
27For piglit tests, you can set:
28
29```
30PIGLIT_PLATFORM=gbm
31WAFFLE_GBM_DEVICE=<path from DRM_SHIM_DEBUG>
32```
33
34See your drm-shim backend's README for details on how to use it.
35