Skip to contentSkip to conversation

drm/doc: Document ioctl errno value patterns

PATCH In review Daniel Vetter 4 participants 4 messages Aug 18, 2017

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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.

Cc Joonas Lahtinen <[email protected]>
Cc Chris Wilson <[email protected]>
Cc "Zhang, Tina" <[email protected]>
---
 Documentation/gpu/drm-uapi.rst | 53 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
Documentation/gpu/drm-uapi.rst +53 -0
index 679373b4a03f..f3cc829467b4 100644
@@ -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
#1 lore raw

✓ 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

Reviewed-by on v1 1/1
#2 lore raw
In reply to Daniel Vetter

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

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
index 679373b4a03f..f3cc829467b4 100644

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

#3 lore raw
In reply to Daniel Vetter

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