Commit 43d5ac7d authored by Simon Ser's avatar Simon Ser
Browse files

drm: document DRM_IOCTL_MODE_GETFB2 



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: default avatarSimon Ser <contact@emersion.fr>
Acked-by: default avatarDaniel Vetter <daniel@ffwll.ch>
Acked-by: default avatarPekka Paalanen <pekka.paalanen@collabora.com>
Acked-by: default avatarDaniel Stone <daniels@collabora.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20211123112400.22245-1-contact@emersion.fr
parent 1c66496b

include/uapi/drm/drm.h

+18 −0
Original line number Diff line number Diff line
@@ -1096,6 +1096,24 @@ extern "C" { 
#define DRM_IOCTL_SYNCOBJ_TRANSFER	DRM_IOWR(0xCC, struct drm_syncobj_transfer)

#define DRM_IOCTL_SYNCOBJ_TIMELINE_SIGNAL	DRM_IOWR(0xCD, struct drm_syncobj_timeline_array)



/**

 * DRM_IOCTL_MODE_GETFB2 - Get framebuffer metadata.

 *

 * This queries metadata about a framebuffer. User-space fills

 * &drm_mode_fb_cmd2.fb_id as the input, and the kernels fills the rest of the

 * struct as the output.

 *

 * If the client is DRM master or has &CAP_SYS_ADMIN, &drm_mode_fb_cmd2.handles

 * will be filled with GEM buffer handles. Planes are valid until one has a

 * zero handle -- this can be used to compute the number of planes.

 *

 * Otherwise, &drm_mode_fb_cmd2.handles will be zeroed and planes are valid

 * until one has a zero &drm_mode_fb_cmd2.pitches.

 *

 * If the framebuffer has a format modifier, &DRM_MODE_FB_MODIFIERS will be set

 * in &drm_mode_fb_cmd2.flags and &drm_mode_fb_cmd2.modifier will contain the

 * modifier. Otherwise, user-space must ignore &drm_mode_fb_cmd2.modifier.

 */

#define DRM_IOCTL_MODE_GETFB2		DRM_IOWR(0xCE, struct drm_mode_fb_cmd2)



/*