| Message ID | 20170818174328.6386-1-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Fri, Aug 18, 2017 at 07:43:28PM +0200, Daniel Vetter wrote: > 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> Pushed to drm-misc-next. -Daniel > --- > Documentation/gpu/drm-uapi.rst | 55 ++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 55 insertions(+) > > 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: > > -- > 2.13.3 >
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: