* [PATCH] drm/doc: Document ioctl errno value patterns
@ 2017-08-18 17:43 Daniel Vetter
2017-08-23 13:09 ` Daniel Vetter
0 siblings, 1 reply; 5+ messages in thread
From: Daniel Vetter @ 2017-08-18 17:43 UTC (permalink / raw)
To: DRI Development
Cc: Daniel Vetter, Intel Graphics Development, Joonas Lahtinen,
Zhang, Tina, 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
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] drm/doc: Document ioctl errno value patterns
2017-08-18 17:43 [PATCH] drm/doc: Document ioctl errno value patterns Daniel Vetter
@ 2017-08-23 13:09 ` Daniel Vetter
0 siblings, 0 replies; 5+ messages in thread
From: Daniel Vetter @ 2017-08-23 13:09 UTC (permalink / raw)
To: DRI Development
Cc: Daniel Vetter, Intel Graphics Development, Joonas Lahtinen,
Zhang, Tina, 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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] drm/doc: Document ioctl errno value patterns
2017-08-18 9:21 Daniel Vetter
2017-08-18 12:05 ` Chris Wilson
@ 2017-08-18 14:26 ` Daniel Stone
1 sibling, 0 replies; 5+ messages in thread
From: Daniel Stone @ 2017-08-18 14:26 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Daniel Vetter, Intel Graphics Development, DRI Development
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] drm/doc: Document ioctl errno value patterns
2017-08-18 9:21 Daniel Vetter
@ 2017-08-18 12:05 ` Chris Wilson
2017-08-18 14:26 ` Daniel Stone
1 sibling, 0 replies; 5+ messages in thread
From: Chris Wilson @ 2017-08-18 12:05 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Daniel Vetter, Intel Graphics Development
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH] drm/doc: Document ioctl errno value patterns
@ 2017-08-18 9:21 Daniel Vetter
2017-08-18 12:05 ` Chris Wilson
2017-08-18 14:26 ` Daniel Stone
0 siblings, 2 replies; 5+ messages in thread
From: Daniel Vetter @ 2017-08-18 9:21 UTC (permalink / raw)
To: DRI Development; +Cc: Daniel Vetter, Intel Graphics Development, 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
^ permalink raw reply related [flat|nested] 5+ messages in thread
end of thread, other threads:[~2017-08-23 13:09 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-08-18 17:43 [PATCH] drm/doc: Document ioctl errno value patterns Daniel Vetter
2017-08-23 13:09 ` Daniel Vetter
-- strict thread matches above, loose matches on Subject: below --
2017-08-18 9:21 Daniel Vetter
2017-08-18 12:05 ` Chris Wilson
2017-08-18 14:26 ` Daniel Stone
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).