drm/doc: Document ioctl errno value patterns
Subsystems (3)
PATCH 1/1 drm/doc: Document ioctl errno value patterns
We're not super-consistent about these, but I think it's worth to document at least the commmon patterns.
--- Documentation/gpu/drm-uapi.rst | 53 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+)
Documentation/gpu/drm-uapi.rst +53 -0
@@ -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 ======================
Signature · 6 lines
2.13.3 _______________________________________________ Intel-gfx mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Patchwork
CI✓ Fi.CI.BAT: success for drm/doc: Document ioctl errno value patterns
== Series Details ==
== Series Details ==
Series: drm/doc: Document ioctl errno value patterns
URL : https://patchwork.freedesktop.org/series/28974/
State : success
== Summary ==
Series 28974v1 drm/doc: Document ioctl errno value patterns
https://patchwork.freedesktop.org/api/1.0/series/28974/revisions/1/mbox/
fi-bdw-5557u total:279 pass:268 dwarn:0 dfail:0 fail:0 skip:11 time:449s fi-blb-e6850 total:279 pass:224 dwarn:1 dfail:0 fail:0 skip:54 time:358s fi-bsw-n3050 total:279 pass:243 dwarn:0 dfail:0 fail:0 skip:36 time:561s fi-bxt-j4205 total:279 pass:260 dwarn:0 dfail:0 fail:0 skip:19 time:516s fi-byt-j1900 total:279 pass:254 dwarn:1 dfail:0 fail:0 skip:24 time:528s fi-byt-n2820 total:279 pass:250 dwarn:1 dfail:0 fail:0 skip:28 time:521s fi-glk-2a total:279 pass:260 dwarn:0 dfail:0 fail:0 skip:19 time:614s fi-hsw-4770 total:279 pass:263 dwarn:0 dfail:0 fail:0 skip:16 time:442s fi-hsw-4770r total:279 pass:263 dwarn:0 dfail:0 fail:0 skip:16 time:421s fi-ilk-650 total:279 pass:229 dwarn:0 dfail:0 fail:0 skip:50 time:421s fi-ivb-3520m total:279 pass:261 dwarn:0 dfail:0 fail:0 skip:18 time:507s fi-ivb-3770 total:279 pass:261 dwarn:0 dfail:0 fail:0 skip:18 time:478s fi-kbl-7500u total:279 pass:261 dwarn:0 dfail:0 fail:0 skip:18 time:472s fi-kbl-7560u total:279 pass:269 dwarn:0 dfail:0 fail:0 skip:10 time:595s fi-kbl-r total:279 pass:261 dwarn:0 dfail:0 fail:0 skip:18 time:601s fi-pnv-d510 total:279 pass:223 dwarn:1 dfail:0 fail:0 skip:55 time:533s fi-skl-6260u total:279 pass:269 dwarn:0 dfail:0 fail:0 skip:10 time:465s fi-skl-6700k total:279 pass:261 dwarn:0 dfail:0 fail:0 skip:18 time:482s fi-skl-6770hq total:279 pass:269 dwarn:0 dfail:0 fail:0 skip:10 time:485s fi-skl-gvtdvm total:279 pass:266 dwarn:0 dfail:0 fail:0 skip:13 time:441s fi-skl-x1585l total:279 pass:268 dwarn:0 dfail:0 fail:0 skip:11 time:480s fi-snb-2520m total:279 pass:251 dwarn:0 dfail:0 fail:0 skip:28 time:546s fi-snb-2600 total:279 pass:250 dwarn:0 dfail:0 fail:0 skip:29 time:407s
fi-bdw-gvtdvm failed to connect after reboot
8183095ca4abce6ec2ad43c1e36e877792c140f1 drm-tip: 2017y-08m-18d-09h-08m-28s UTC integration manifest 4531132c0c7a drm/doc: Document ioctl errno value patterns
== Logs ==
For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_5435/
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Quoting Daniel Vetter (2017-08-18 10:21:24)
Quoted 7 lines
We're not super-consistent about these, but I think it's worth to document at least the commmon patterns.
Cc Joonas Lahtinen <[email protected]>Cc Chris Wilson <[email protected]>Cc "Zhang, Tina" <[email protected]>Signed-off-by Daniel Vetter <[email protected]>
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.
Quoted 9 lines
--- Documentation/gpu/drm-uapi.rst | 53 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+)Documentation/gpu/drm-uapi.rst +0
-0
Documentation/gpu/drm-uapi.rst IOCTL Support on Device Nodes · line 181
Quoted 5 lines
Documentation/gpu/drm-uapi.rst +2
-0@@ -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 [email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Hi,
Documentation/gpu/drm-uapi.rst IOCTL Support on Device Nodes
Quoted 9 lines · Daniel Vetter
Documentation/gpu/drm-uapi.rst +9
-0+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.
Documentation/gpu/drm-uapi.rst IOCTL Support on Device Nodes
Quoted 6 lines
Documentation/gpu/drm-uapi.rst +6
-0+ 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
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx