linux-toradex.git/include/uapi/drm/drm.h, branch v6.7-rc3

drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB

2023-10-25T15:32:56+00:00

The main motivation is to repeat that dumb buffers should not be
abused for anything else than basic software rendering with KMS.
User-space devs are more likely to look at the IOCTL docs than to
actively search for the driver-oriented "Dumb Buffer Objects"
section.

v2: reference DRM_CAP_DUMB_BUFFER, DRM_CAP_DUMB_PREFERRED_DEPTH and
DRM_CAP_DUMB_PREFER_SHADOW (Pekka)

Signed-off-by: Simon Ser 
Acked-by: Daniel Vetter 
Acked-by: Pekka Paalanen 
Link: https://patchwork.freedesktop.org/patch/msgid/20230821131548.269204-1-contact@emersion.fr

drm/doc: document that PRIME import/export is always supported

2023-08-03T10:29:13+00:00

Since commit 6b85aa68d9d5 ("drm: Enable PRIME import/export for all
drivers"), import/export is always supported. Document this so that
user-space knows what to expect.

Signed-off-by: Simon Ser 
Reviewed-by: Jeffrey Hugo 
Cc: Thomas Zimmermann 
Cc: Alex Deucher 
Cc: Jeffrey Hugo 
Cc: Daniel Vetter 
Link: https://patchwork.freedesktop.org/patch/msgid/20230712183156.191445-1-contact@emersion.fr

drm/doc: document drm_event and its types

2023-08-03T10:18:57+00:00

Convert struct drm_event to a kernel doc comment. Link to the
generic DRM event types. Add a basic description of each event
type.

Signed-off-by: Simon Ser 
Acked-by: Pekka Paalanen 
Acked-by: Daniel Vetter 
Link: https://patchwork.freedesktop.org/patch/msgid/20230717093032.600773-1-contact@emersion.fr

drm/doc: use proper cross-references for sections

2023-08-03T10:17:29+00:00

When I originally wrote these docs, I couldn't manage to insert a
cross-reference to a section. Here's how it can be done.

Signed-off-by: Simon Ser 
Reviewed-by: Jani Nikula 
Acked-by: Daniel Vetter 
Cc: Pekka Paalanen 
Link: https://patchwork.freedesktop.org/patch/msgid/20230803095734.386761-1-contact@emersion.fr

drm/syncobj: add IOCTL to register an eventfd

2023-07-20T10:01:03+00:00

Introduce a new DRM_IOCTL_SYNCOBJ_EVENTFD IOCTL which signals an
eventfd from a syncobj.

This is useful for Wayland compositors to handle wait-before-submit.
Wayland clients can send a timeline point to the compositor
before the point has materialized yet, then compositors can wait
for the point to materialize via this new IOCTL.

The existing DRM_IOCTL_SYNCOBJ_TIMELINE_WAIT IOCTL is not suitable
because it blocks. Compositors want to integrate the wait with
their poll(2)-based event loop.

Requirements for new uAPI:

- User-space patch: https://gitlab.freedesktop.org/wlroots/wlroots/-/merge_requests/4262
- IGT: https://lists.freedesktop.org/archives/igt-dev/2023-July/057893.html

v2:
- Wait for fence when flags is zero
- Improve documentation (Pekka)
- Rename IOCTL (Christian)
- Fix typo in drm_syncobj_add_eventfd() (Christian)

v3:
- Link user-space + IGT patches
- Add reference from overview docs

v4: fix IOCTL number conflict with GETFB2 (Nicholas Choi, Vitaly Prosyak)

Signed-off-by: Simon Ser 
Reviewed-by: Christian König 
Acked-by: Pekka Paalanen 
Cc: Jason Ekstrand 
Cc: Daniel Vetter 
Cc: Bas Nieuwenhuizen 
Cc: Daniel Stone 
Cc: James Jones 
Cc: Austin Shafer 
Cc: Vitaly Prosyak 
Link: https://patchwork.freedesktop.org/patch/msgid/20230714111257.11940-1-contact@emersion.fr

drm: document DRM_IOCTL_PRIME_HANDLE_TO_FD and PRIME_FD_TO_HANDLE

2023-02-20T09:42:00+00:00

v2: mention caps, note that the IOCTLs might fail, document that
user-space needs a data structure to keep track of the
handles (Daniel V.)

Signed-off-by: Simon Ser 
Cc: Daniel Vetter 
Cc: Pekka Paalanen 
Cc: Daniel Stone 
Reviewed-by: Daniel Vetter 
Acked-by: Pekka Paalanen 
Link: https://patchwork.freedesktop.org/patch/msgid/20230217162151.59996-2-contact@emersion.fr

drm: document expectations for GETFB2 handles

2023-02-20T09:41:43+00:00

There are two important details missing from the docs:

- If the memory object backing the FB already has a GEM handle,
  it's not re-used, a new one is generated.
- Aliased planes will return the same GEM handle.

v2: document how user-space can obtain DMA-BUF FDs without leaking
handles (Pekka)

Signed-off-by: Simon Ser 
Cc: Daniel Vetter 
Cc: Pekka Paalanen 
Cc: Daniel Stone 
Acked-by: Pekka Paalanen 
Reviewed-by: Daniel Vetter 
Link: https://patchwork.freedesktop.org/patch/msgid/20230217162151.59996-1-contact@emersion.fr

drm: document DRM_IOCTL_GEM_CLOSE

2023-02-17T09:30:49+00:00

This is a bit tricky, because of the ref'counting considerations.
See also [1] for more discussion about this topic. Since this is
kernel docs, I've decided to elaborate a bit less on the user-space
details.

[1]: https://gitlab.freedesktop.org/mesa/drm/-/merge_requests/110

Signed-off-by: Simon Ser 
Cc: Daniel Vetter 
Cc: Pekka Paalanen 
Cc: Daniel Stone 
Reviewed-by: Daniel Vetter 
Acked-by: Pekka Paalanen 
Link: https://patchwork.freedesktop.org/patch/msgid/20230216130934.156541-2-contact@emersion.fr

drm: document DRM_IOCTL_MODE_GETFB2

2021-12-14T11:03:32+00:00

There are a few details specific to the GETFB2 IOCTL.

It's not immediately clear how user-space should check for the
number of planes. Suggest using the handles field or the pitches
field.

The modifier array is filled with zeroes, ie. DRM_FORMAT_MOD_LINEAR.
So explicitly tell user-space to not look at it unless the flag is
set.

Changes in v2 (Daniel):
- Mention that handles should be used to compute the number of planes,
  and only refer to pitches as a fallback.
- Reword bit about undefined modifier.

Signed-off-by: Simon Ser 
Acked-by: Daniel Vetter 
Acked-by: Pekka Paalanen 
Acked-by: Daniel Stone 
Link: https://patchwork.freedesktop.org/patch/msgid/20211123112400.22245-1-contact@emersion.fr

drm: document DRM_IOCTL_MODE_RMFB

2021-07-27T12:23:36+00:00

Since there's no struct to attach the docs to, document the IOCTL
definition.

Signed-off-by: Simon Ser 
Reviewed-by: Pekka Paalanen 
Reviewed-by: Daniel Vetter 
Cc: Leandro Ribeiro 
Link: https://patchwork.freedesktop.org/patch/msgid/ephVkof3uGu2RpOdBbrHE3qF98zBfIBRzXe4Vyoboh0@cp4-web-034.plabs.ch