[PATCH] drm/doc: Document ioctl errno value patterns

[PATCH] drm/doc: Document ioctl errno value patterns

[Daniel Vetter]

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(+)

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@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH] drm/doc: Document ioctl errno value patterns

[Chris Wilson]

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
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH] drm/doc: Document ioctl errno value patterns

[Daniel Stone]

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
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH] drm/doc: Document ioctl errno value patterns

[Daniel Vetter]

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
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH] drm/doc: Document ioctl errno value patterns

[Daniel Vetter]

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>
---
 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

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel