Commit a3574119 authored by Simon Ser's avatar Simon Ser
Browse files

drm: document struct drm_mode_fb_cmd2 



Follow-up for the DRM_IOCTL_MODE_GETFB2 docs.

v2: (Daniel Stone)
- Replace fourcc.org with drm_fourcc.h because this is the
  authoritative source and the website may have mismatches.
- Drop assumption that offsets will generally be 0.
- Mention that unused entries must be zero'ed out.

v3: (Pekka)
- Mention that a handle can be re-used
- Add unit for pitches/offsets

Signed-off-by: default avatarSimon Ser <contact@emersion.fr>
Reviewed-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Acked-by: default avatarPekka Paalanen <pekka.paalanen@collabora.com>
Cc: Daniel Stone <daniels@collabora.com>
Reviewed-by: default avatarDaniel Stone <daniels@collabora.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20220203133753.261507-1-contact@emersion.fr
parent eea89dff

include/uapi/drm/drm_mode.h

+60 −28
Original line number Diff line number Diff line
@@ -663,41 +663,73 @@ struct drm_mode_fb_cmd { 
#define DRM_MODE_FB_INTERLACED	(1<<0) /* for interlaced framebuffers */

#define DRM_MODE_FB_MODIFIERS	(1<<1) /* enables ->modifer[] */



/**

 * struct drm_mode_fb_cmd2 - Frame-buffer metadata.

 *

 * This struct holds frame-buffer metadata. There are two ways to use it:

 *

 * - User-space can fill this struct and perform a &DRM_IOCTL_MODE_ADDFB2

 *   ioctl to register a new frame-buffer. The new frame-buffer object ID will

 *   be set by the kernel in @fb_id.

 * - User-space can set @fb_id and perform a &DRM_IOCTL_MODE_GETFB2 ioctl to

 *   fetch metadata about an existing frame-buffer.

 *

 * In case of planar formats, this struct allows up to 4 buffer objects with

 * offsets and pitches per plane. The pitch and offset order is dictated by the

 * format FourCC as defined by ``drm_fourcc.h``, e.g. NV12 is described as:

 *

 *     YUV 4:2:0 image with a plane of 8 bit Y samples followed by an

 *     interleaved U/V plane containing 8 bit 2x2 subsampled colour difference

 *     samples.

 *

 * So it would consist of a Y plane at ``offsets[0]`` and a UV plane at

 * ``offsets[1]``.

 *

 * To accommodate tiled, compressed, etc formats, a modifier can be specified.

 * For more information see the "Format Modifiers" section. Note that even

 * though it looks like we have a modifier per-plane, we in fact do not. The

 * modifier for each plane must be identical. Thus all combinations of

 * different data layouts for multi-plane formats must be enumerated as

 * separate modifiers.

 *

 * All of the entries in @handles, @pitches, @offsets and @modifier must be

 * zero when unused. Warning, for @offsets and @modifier zero can't be used to

 * figure out whether the entry is used or not since it's a valid value (a zero

 * offset is common, and a zero modifier is &DRM_FORMAT_MOD_LINEAR).

 */

struct drm_mode_fb_cmd2 {

	/** @fb_id: Object ID of the frame-buffer. */

	__u32 fb_id;

	/** @width: Width of the frame-buffer. */

	__u32 width;

	/** @height: Height of the frame-buffer. */

	__u32 height;

	__u32 pixel_format; /* fourcc code from drm_fourcc.h */

	__u32 flags; /* see above flags */

	/**

	 * @pixel_format: FourCC format code, see ``DRM_FORMAT_*`` constants in

	 * ``drm_fourcc.h``.

	 */

	__u32 pixel_format;

	/**

	 * @flags: Frame-buffer flags (see &DRM_MODE_FB_INTERLACED and

	 * &DRM_MODE_FB_MODIFIERS).

	 */

	__u32 flags;



	/*

	 * In case of planar formats, this ioctl allows up to 4

	 * buffer objects with offsets and pitches per plane.

	 * The pitch and offset order is dictated by the fourcc,

	 * e.g. NV12 (https://fourcc.org/yuv.php#NV12) is described as:

	 *

	 *   YUV 4:2:0 image with a plane of 8 bit Y samples

	 *   followed by an interleaved U/V plane containing

	 *   8 bit 2x2 subsampled colour difference samples.

	 *

	 * So it would consist of Y as offsets[0] and UV as

	 * offsets[1].  Note that offsets[0] will generally

	 * be 0 (but this is not required).

	 *

	 * To accommodate tiled, compressed, etc formats, a

	 * modifier can be specified.  The default value of zero

	 * indicates "native" format as specified by the fourcc.

	 * Vendor specific modifier token.  Note that even though

	 * it looks like we have a modifier per-plane, we in fact

	 * do not. The modifier for each plane must be identical.

	 * Thus all combinations of different data layouts for

	 * multi plane formats must be enumerated as separate

	 * modifiers.

	/**

	 * @handles: GEM buffer handle, one per plane. Set to 0 if the plane is

	 * unused. The same handle can be used for multiple planes.

	 */

	__u32 handles[4];

	__u32 pitches[4]; /* pitch for each plane */

	__u32 offsets[4]; /* offset of each plane */

	__u64 modifier[4]; /* ie, tiling, compress */

	/** @pitches: Pitch (aka. stride) in bytes, one per plane. */

	__u32 pitches[4];

	/** @offsets: Offset into the buffer in bytes, one per plane. */

	__u32 offsets[4];

	/**

	 * @modifier: Format modifier, one per plane. See ``DRM_FORMAT_MOD_*``

	 * constants in ``drm_fourcc.h``. All planes must use the same

	 * modifier. Ignored unless &DRM_MODE_FB_MODIFIERS is set in @flags.

	 */

	__u64 modifier[4];

};



#define DRM_MODE_FB_DIRTY_ANNOTATE_COPY 0x01