Documentation/process/botching-up-ioctls.rst

5 From: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html
13 Which is nice, since there's no more insanity in the form of fake-generic, but
18 lessons learned while botching the job for the drm/i915 driver. Most of these
19 only cover technicalities and not the big-picture issues like what the command
25 -------------
28 will need to add a 32-bit compat layer:
33  * Align everything to the natural size and use explicit padding. 32-bit
34    platforms don't necessarily align 64-bit values to 64-bit boundaries, but
35    64-bit platforms do. So we always need padding to the natural size to get
36    this right.
38  * Pad the entire struct to a multiple of 64-bits if the structure contains
39    64-bit types - the structure size will otherwise differ on 32-bit versus
40    64-bit. Having a different structure size hurts when passing arrays of
53 ------
66    the structure. The drm core checks the passed-in size for each ioctl call
67    and zero-extends any mismatches between kernel and userspace. That helps,
74    future extensions is going right down the gutters since someone will submit
78    structures, even if you never use them in an array - the padding the compiler
85 --------------------
89 error handling paths - GPUs will die eventually in the oddmost corner cases
111    how you handle ioctl restarting - e.g. drm has a tiny drmIoctl helper in its
119    still too tricky have a timeout or hangcheck safety net as a last-ditch
123    - it's way too easy to create a deadlock between your hangcheck code and
128 ----------------------------
130 GPUs do most everything asynchronously, so we have a need to time operations and
132 the ioctls supported by the drm/i915 get this fully right, which means there's
141    get at the raw values of some clocks (e.g. through in-command-stream
144  * Use __s64 seconds plus __u64 nanoseconds to specify time. It's not the most
156    always be extended - but users will surely hate you if their neat animations
163  * Have testcases for corner-cases, especially whether the return values for
164    already-completed events, successful waits and timed-out waits are all sane
169 ----------------------
171 A full-blown drm driver essentially implements a little OS, but specialized to
173 for different objects and other resources to userspace. Doing that right
178    needs to be shared across processes -  fd-passing over unix domain sockets
184    default pick a private per-fd namespace which forces any sharing to be done
185    explicitly. Only go with a more global per-device namespace if the objects
186    are truly device-unique. One counterexample in the drm modeset interfaces is
187    that the per-device modeset objects like connectors share a namespace with
192  * Think about uniqueness requirements for userspace handles. E.g. for most drm
198    as unique identifiers - it's how real files are told apart, too.
199    Unfortunately this requires a full-blown virtual filesystem in the kernel.
203 -------------------
207  * Think hard whether you really want a driver-private interface. Of course
208    it's much quicker to push a driver-private interface than engaging in
215    per-device settings, or for child objects with fairly static lifetimes (like
220 Finally, the name of the game is to get it right on the first attempt, since if
221 your driver proves popular and your hardware platforms long-lived then you'll