We're not super-consistent about these, but I think it's worth to
document at least the commmon patterns.
Cc: Joonas Lahtinen <joonas.lahtinen@xxxxxxxxxxxxxxx>
Cc: Chris Wilson <chris@xxxxxxxxxxxxxxxxxx>
Cc: "Zhang, Tina" <tina.zhang@xxxxxxxxx>
Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx>
---
Documentation/gpu/drm-uapi.rst | 53 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 53 insertions(+)
diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 679373b4a03f..f3cc829467b4 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -177,6 +177,59 @@ IOCTL Support on Device Nodes
.. kernel-doc:: drivers/gpu/drm/drm_ioc32.c
:export:
+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 speaking only when you try to open isn't there. 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 differiante "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 priviledges.
+ E.g. root-only or much more common, DRM master-only operations return
+ this when when called by unpriviledges 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, but their usage is
+in line with the common meanings. The above list tries to just document DRM
+specific patterns.
+
Testing and validation
======================
--
2.13.3
_______________________________________________
Intel-gfx mailing list
Intel-gfx@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
