diff options
Diffstat (limited to 'Documentation/ioctl/botching-up-ioctls.rst')
| -rw-r--r-- | Documentation/ioctl/botching-up-ioctls.rst | 225 |
1 files changed, 0 insertions, 225 deletions
diff --git a/Documentation/ioctl/botching-up-ioctls.rst b/Documentation/ioctl/botching-up-ioctls.rst deleted file mode 100644 index ac697fef3545..000000000000 --- a/Documentation/ioctl/botching-up-ioctls.rst +++ /dev/null @@ -1,225 +0,0 @@ -================================= -(How to avoid) Botching up ioctls -================================= - -From: http://blog.ffwll.ch/2013/11/botching-up-ioctls.html - -By: Daniel Vetter, Copyright © 2013 Intel Corporation - -One clear insight kernel graphics hackers gained in the past few years is that -trying to come up with a unified interface to manage the execution units and -memory on completely different GPUs is a futile effort. So nowadays every -driver has its own set of ioctls to allocate memory and submit work to the GPU. -Which is nice, since there's no more insanity in the form of fake-generic, but -actually only used once interfaces. But the clear downside is that there's much -more potential to screw things up. - -To avoid repeating all the same mistakes again I've written up some of the -lessons learned while botching the job for the drm/i915 driver. Most of these -only cover technicalities and not the big-picture issues like what the command -submission ioctl exactly should look like. Learning these lessons is probably -something every GPU driver has to do on its own. - - -Prerequisites -------------- - -First the prerequisites. Without these you have already failed, because you -will need to add a 32-bit compat layer: - - * Only use fixed sized integers. To avoid conflicts with typedefs in userspace - the kernel has special types like __u32, __s64. Use them. - - * Align everything to the natural size and use explicit padding. 32-bit - platforms don't necessarily align 64-bit values to 64-bit boundaries, but - 64-bit platforms do. So we always need padding to the natural size to get - this right. - - * Pad the entire struct to a multiple of 64-bits if the structure contains - 64-bit types - the structure size will otherwise differ on 32-bit versus - 64-bit. Having a different structure size hurts when passing arrays of - structures to the kernel, or if the kernel checks the structure size, which - e.g. the drm core does. - - * Pointers are __u64, cast from/to a uintprt_t on the userspace side and - from/to a void __user * in the kernel. Try really hard not to delay this - conversion or worse, fiddle the raw __u64 through your code since that - diminishes the checking tools like sparse can provide. The macro - u64_to_user_ptr can be used in the kernel to avoid warnings about integers - and pointres of different sizes. - - -Basics ------- - -With the joys of writing a compat layer avoided we can take a look at the basic -fumbles. Neglecting these will make backward and forward compatibility a real -pain. And since getting things wrong on the first attempt is guaranteed you -will have a second iteration or at least an extension for any given interface. - - * Have a clear way for userspace to figure out whether your new ioctl or ioctl - extension is supported on a given kernel. If you can't rely on old kernels - rejecting the new flags/modes or ioctls (since doing that was botched in the - past) then you need a driver feature flag or revision number somewhere. - - * Have a plan for extending ioctls with new flags or new fields at the end of - the structure. The drm core checks the passed-in size for each ioctl call - and zero-extends any mismatches between kernel and userspace. That helps, - but isn't a complete solution since newer userspace on older kernels won't - notice that the newly added fields at the end get ignored. So this still - needs a new driver feature flags. - - * Check all unused fields and flags and all the padding for whether it's 0, - and reject the ioctl if that's not the case. Otherwise your nice plan for - future extensions is going right down the gutters since someone will submit - an ioctl struct with random stack garbage in the yet unused parts. Which - then bakes in the ABI that those fields can never be used for anything else - but garbage. This is also the reason why you must explicitly pad all - structures, even if you never use them in an array - the padding the compiler - might insert could contain garbage. - - * Have simple testcases for all of the above. - - -Fun with Error Paths --------------------- - -Nowadays we don't have any excuse left any more for drm drivers being neat -little root exploits. This means we both need full input validation and solid -error handling paths - GPUs will die eventually in the oddmost corner cases -anyway: - - * The ioctl must check for array overflows. Also it needs to check for - over/underflows and clamping issues of integer values in general. The usual - example is sprite positioning values fed directly into the hardware with the - hardware just having 12 bits or so. Works nicely until some odd display - server doesn't bother with clamping itself and the cursor wraps around the - screen. - - * Have simple testcases for every input validation failure case in your ioctl. - Check that the error code matches your expectations. And finally make sure - that you only test for one single error path in each subtest by submitting - otherwise perfectly valid data. Without this an earlier check might reject - the ioctl already and shadow the codepath you actually want to test, hiding - bugs and regressions. - - * Make all your ioctls restartable. First X really loves signals and second - this will allow you to test 90% of all error handling paths by just - interrupting your main test suite constantly with signals. Thanks to X's - love for signal you'll get an excellent base coverage of all your error - paths pretty much for free for graphics drivers. Also, be consistent with - how you handle ioctl restarting - e.g. drm has a tiny drmIoctl helper in its - userspace library. The i915 driver botched this with the set_tiling ioctl, - now we're stuck forever with some arcane semantics in both the kernel and - userspace. - - * If you can't make a given codepath restartable make a stuck task at least - killable. GPUs just die and your users won't like you more if you hang their - entire box (by means of an unkillable X process). If the state recovery is - still too tricky have a timeout or hangcheck safety net as a last-ditch - effort in case the hardware has gone bananas. - - * Have testcases for the really tricky corner cases in your error recovery code - - it's way too easy to create a deadlock between your hangcheck code and - waiters. - - -Time, Waiting and Missing it ----------------------------- - -GPUs do most everything asynchronously, so we have a need to time operations and -wait for outstanding ones. This is really tricky business; at the moment none of -the ioctls supported by the drm/i915 get this fully right, which means there's -still tons more lessons to learn here. - - * Use CLOCK_MONOTONIC as your reference time, always. It's what alsa, drm and - v4l use by default nowadays. But let userspace know which timestamps are - derived from different clock domains like your main system clock (provided - by the kernel) or some independent hardware counter somewhere else. Clocks - will mismatch if you look close enough, but if performance measuring tools - have this information they can at least compensate. If your userspace can - get at the raw values of some clocks (e.g. through in-command-stream - performance counter sampling instructions) consider exposing those also. - - * Use __s64 seconds plus __u64 nanoseconds to specify time. It's not the most - convenient time specification, but it's mostly the standard. - - * Check that input time values are normalized and reject them if not. Note - that the kernel native struct ktime has a signed integer for both seconds - and nanoseconds, so beware here. - - * For timeouts, use absolute times. If you're a good fellow and made your - ioctl restartable relative timeouts tend to be too coarse and can - indefinitely extend your wait time due to rounding on each restart. - Especially if your reference clock is something really slow like the display - frame counter. With a spec lawyer hat on this isn't a bug since timeouts can - always be extended - but users will surely hate you if their neat animations - starts to stutter due to this. - - * Consider ditching any synchronous wait ioctls with timeouts and just deliver - an asynchronous event on a pollable file descriptor. It fits much better - into event driven applications' main loop. - - * Have testcases for corner-cases, especially whether the return values for - already-completed events, successful waits and timed-out waits are all sane - and suiting to your needs. - - -Leaking Resources, Not ----------------------- - -A full-blown drm driver essentially implements a little OS, but specialized to -the given GPU platforms. This means a driver needs to expose tons of handles -for different objects and other resources to userspace. Doing that right -entails its own little set of pitfalls: - - * Always attach the lifetime of your dynamically created resources to the - lifetime of a file descriptor. Consider using a 1:1 mapping if your resource - needs to be shared across processes - fd-passing over unix domain sockets - also simplifies lifetime management for userspace. - - * Always have O_CLOEXEC support. - - * Ensure that you have sufficient insulation between different clients. By - default pick a private per-fd namespace which forces any sharing to be done - explicitly. Only go with a more global per-device namespace if the objects - are truly device-unique. One counterexample in the drm modeset interfaces is - that the per-device modeset objects like connectors share a namespace with - framebuffer objects, which mostly are not shared at all. A separate - namespace, private by default, for framebuffers would have been more - suitable. - - * Think about uniqueness requirements for userspace handles. E.g. for most drm - drivers it's a userspace bug to submit the same object twice in the same - command submission ioctl. But then if objects are shareable userspace needs - to know whether it has seen an imported object from a different process - already or not. I haven't tried this myself yet due to lack of a new class - of objects, but consider using inode numbers on your shared file descriptors - as unique identifiers - it's how real files are told apart, too. - Unfortunately this requires a full-blown virtual filesystem in the kernel. - - -Last, but not Least -------------------- - -Not every problem needs a new ioctl: - - * Think hard whether you really want a driver-private interface. Of course - it's much quicker to push a driver-private interface than engaging in - lengthy discussions for a more generic solution. And occasionally doing a - private interface to spearhead a new concept is what's required. But in the - end, once the generic interface comes around you'll end up maintainer two - interfaces. Indefinitely. - - * Consider other interfaces than ioctls. A sysfs attribute is much better for - per-device settings, or for child objects with fairly static lifetimes (like - output connectors in drm with all the detection override attributes). Or - maybe only your testsuite needs this interface, and then debugfs with its - disclaimer of not having a stable ABI would be better. - -Finally, the name of the game is to get it right on the first attempt, since if -your driver proves popular and your hardware platforms long-lived then you'll -be stuck with a given ioctl essentially forever. You can try to deprecate -horrible ioctls on newer iterations of your hardware, but generally it takes -years to accomplish this. And then again years until the last user able to -complain about regressions disappears, too. |