| Message ID | 20170818092124.32339-1-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
Quoting Daniel Vetter (2017-08-18 10:21:24) > 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@linux.intel.com> > Cc: Chris Wilson <chris@chris-wilson.co.uk> > Cc: "Zhang, Tina" <tina.zhang@intel.com> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> One extra used outside of i915 is ENOSYS. Perhaps nouveau/vmgfx might like to chime in if that's exposed to userspace and is a good pattern you'ld like DRM as a whole to pick up. As far as i915, these do capture our uses very well. Reviewed-by: Chris Wilson <chris@chris-wilson.co.uk> > --- > 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 > +=============================== Would this not be a preface to @drm_driver.ioctl() ? -Chris
Hi, On 18 August 2017 at 10:21, Daniel Vetter <daniel.vetter@ffwll.ch> wrote: > +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. There's a word from this sentence. > + 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 'differentiate' Cheers, Daniel
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 ======================
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@linux.intel.com> Cc: Chris Wilson <chris@chris-wilson.co.uk> Cc: "Zhang, Tina" <tina.zhang@intel.com> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> --- Documentation/gpu/drm-uapi.rst | 53 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+)