On Thu, Jan 20, 2022 at 1:48 PM Simon Ser <contact@xxxxxxxxxxx> wrote:
>
> Follow-up for the DRM_IOCTL_MODE_GETFB2 docs.
>
> Signed-off-by: Simon Ser <contact@xxxxxxxxxxx>
> Cc: Daniel Vetter <daniel@xxxxxxxx>
> Cc: Pekka Paalanen <pekka.paalanen@xxxxxxxxxxxxx>
> Cc: Daniel Stone <daniels@xxxxxxxxxxxxx>
Thanks for pushing our docs forward!
Reviewed-by: Daniel Vetter <daniel.vetter@xxxxxxxx>
> ---
> include/uapi/drm/drm_mode.h | 83 ++++++++++++++++++++++++-------------
> 1 file changed, 55 insertions(+), 28 deletions(-)
>
> diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> index e1e351682872..5dbbe1393bff 100644
> --- a/include/uapi/drm/drm_mode.h
> +++ b/include/uapi/drm/drm_mode.h
> @@ -663,41 +663,68 @@ 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 an &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
> + * 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.
> + * 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.
> + */
> 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.
> */
> __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), one per plane. */
> + __u32 pitches[4];
> + /** @offsets: Offset into the buffer, 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
>
> base-commit: 37e0321ab2569b44f8a94339bf47653493ac864e
> --
> 2.34.1
>
>
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
