Commit 371cadd8 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm/doc: Document ioctl errno value patterns 



We're not super-consistent about these, but I think it's worth to
document at least the commmon patterns.

v2:
- Add a not about ENOTTY (it's just a confusing name, but used
exactly what it's meant for in DRM) (Chris).
- Unconfuse the text for ENODEV (Daniel)
- Move text undert the IOCTL heading (Chris).
- typos

Cc: Daniel Stone <daniel@fooishbar.org>
Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
Cc: Chris Wilson <chris@chris-wilson.co.uk>
Cc: "Zhang, Tina" <tina.zhang@intel.com>
Reviewed-by: default avatarChris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20170818174328.6386-1-daniel.vetter@ffwll.ch
parent 25a8ef26

Documentation/gpu/drm-uapi.rst

+55 −0
Original line number Diff line number Diff line
@@ -168,6 +168,61 @@ IOCTL Support on Device Nodes 
.. kernel-doc:: drivers/gpu/drm/drm_ioctl.c

   :doc: driver specific ioctls



Recommended IOCTL Return Values

-------------------------------



In theory a driver's IOCTL callback is only allowed to return very few error

codes. In practice it's good to abuse a few more. This section documents common

practice within the DRM subsystem:



ENOENT:

        Strictly this should only be used when a file doesn't exist e.g. when

        calling the open() syscall. We reuse that to signal any kind of object

        lookup failure, e.g. for unknown GEM buffer object handles, unknown KMS

        object handles and similar cases.



ENOSPC:

        Some drivers use this to differentiate "out of kernel memory" from "out

        of VRAM". Sometimes also applies to other limited gpu resources used for

        rendering (e.g. when you have a special limited compression buffer).

        Sometimes resource allocation/reservation issues in command submission

        IOCTLs are also signalled through EDEADLK.



        Simply running out of kernel/system memory is signalled through ENOMEM.



EPERM/EACCESS:

        Returned for an operation that is valid, but needs more privileges.

        E.g. root-only or much more common, DRM master-only operations return

        this when when called by unpriviledged clients. There's no clear

        difference between EACCESS and EPERM.



ENODEV:

        Feature (like PRIME, modesetting, GEM) is not supported by the driver.



ENXIO:

        Remote failure, either a hardware transaction (like i2c), but also used

        when the exporting driver of a shared dma-buf or fence doesn't support a

        feature needed.



EINTR:

        DRM drivers assume that userspace restarts all IOCTLs. Any DRM IOCTL can

        return EINTR and in such a case should be restarted with the IOCTL

        parameters left unchanged.



EIO:

        The GPU died and couldn't be resurrected through a reset. Modesetting

        hardware failures are signalled through the "link status" connector

        property.



EINVAL:

        Catch-all for anything that is an invalid argument combination which

        cannot work.



IOCTL also use other error codes like ETIME, EFAULT, EBUSY, ENOTTY but their

usage is in line with the common meanings. The above list tries to just document

DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of

"this IOCTL does not exist", and is used exactly as such in DRM.



.. kernel-doc:: include/drm/drm_ioctl.h

   :internal: