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
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
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 ------
65  * Have a plan for extending ioctls with new flags or new fields at the end of
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,
69    notice that the newly added fields at the end get ignored. So this still
78    structures, even if you never use them in an array - the padding the compiler
85 --------------------
87 Nowadays we don't have any excuse left any more for drm drivers being neat
88 little root exploits. This means we both need full input validation and solid
89 error handling paths - GPUs will die eventually in the oddmost corner cases
99  * Have simple testcases for every input validation failure case in your ioctl.
101    that you only test for one single error path in each subtest by submitting
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 ----------------------------
141    get at the raw values of some clocks (e.g. through in-command-stream
147  * Check that input time values are normalized and reject them if not. Note
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
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
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
211    end, once the generic interface comes around you'll end up maintaining two
215    per-device settings, or for child objects with fairly static lifetimes (like
221 your driver proves popular and your hardware platforms long-lived then you'll