summaryrefslogtreecommitdiff
path: root/Documentation/gpu
diff options
context:
space:
mode:
authorDaniel Vetter <daniel.vetter@ffwll.ch>2017-08-18 19:43:28 +0200
committerDaniel Vetter <daniel.vetter@ffwll.ch>2017-08-23 15:09:26 +0200
commit371cadd8c48c8766ec3e3ca3e0d0a6261f2a8cc0 (patch)
treee6a9a01d0249cd7ce336e98850412aed83797cf7 /Documentation/gpu
parent25a8ef26fd47e4b60cfae094a43ad9bfc49e676b (diff)
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: Chris Wilson <chris@chris-wilson.co.uk> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Link: https://patchwork.freedesktop.org/patch/msgid/20170818174328.6386-1-daniel.vetter@ffwll.ch
Diffstat (limited to 'Documentation/gpu')
-rw-r--r--Documentation/gpu/drm-uapi.rst55
1 files changed, 55 insertions, 0 deletions
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: