From 371cadd8c48c8766ec3e3ca3e0d0a6261f2a8cc0 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 18 Aug 2017 19:43:28 +0200 Subject: 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 Cc: Joonas Lahtinen Cc: Chris Wilson Cc: "Zhang, Tina" Reviewed-by: Chris Wilson Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20170818174328.6386-1-daniel.vetter@ffwll.ch --- Documentation/gpu/drm-uapi.rst | 55 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 679373b4a03f..a2214cc1f821 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -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: -- cgit