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@xxxxxxxxxxxxx> > Cc: Joonas Lahtinen <joonas.lahtinen@xxxxxxxxxxxxxxx> > Cc: Chris Wilson <chris@xxxxxxxxxxxxxxxxxx> > Cc: "Zhang, Tina" <tina.zhang@xxxxxxxxx> > Reviewed-by: Chris Wilson <chris@xxxxxxxxxxxxxxxxxx> > Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx> 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 > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ dri-devel mailing list dri-devel@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/dri-devel
