Commit 61a55f8b authored by Simon Ser's avatar Simon Ser
Browse files

drm: document expectations for GETFB2 handles 



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: default avatarSimon Ser <contact@emersion.fr>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Pekka Paalanen <ppaalanen@gmail.com>
Cc: Daniel Stone <daniel@fooishbar.org>
Acked-by: default avatarPekka Paalanen <pekka.paalanen@collabora.com>
Reviewed-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20230217162151.59996-1-contact@emersion.fr
parent c2f2c721

include/uapi/drm/drm.h

+12 −2
Original line number Original line Diff line number Diff line
@@ -1117,8 +1117,13 @@ extern "C" { 
 * struct as the output.

 * struct as the output.

 *

 *

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

 * 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

 * will be filled with GEM buffer handles. Fresh new GEM handles are always

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

 * returned, even if another GEM handle referring to the same memory object

 * already exists on the DRM file description. The caller is responsible for

 * removing the new handles, e.g. via the &DRM_IOCTL_GEM_CLOSE IOCTL. The same

 * new handle will be returned for multiple planes in case they use the same

 * memory object. 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

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

 * until one has a zero &drm_mode_fb_cmd2.pitches.

 * until one has a zero &drm_mode_fb_cmd2.pitches.
@@ -1126,6 +1131,11 @@ extern "C" { 
 * If the framebuffer has a format modifier, &DRM_MODE_FB_MODIFIERS will be set

 * 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

 * 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.

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

 *

 * To obtain DMA-BUF FDs for each plane without leaking GEM handles, user-space

 * can export each handle via &DRM_IOCTL_PRIME_HANDLE_TO_FD, then immediately

 * close each unique handle via &DRM_IOCTL_GEM_CLOSE, making sure to not

 * double-close handles which are specified multiple times in the array.

 */

 */

#define DRM_IOCTL_MODE_GETFB2		DRM_IOWR(0xCE, struct drm_mode_fb_cmd2)

#define DRM_IOCTL_MODE_GETFB2		DRM_IOWR(0xCE, struct drm_mode_fb_cmd2)