[PATCH] drm: document struct drm_mode_fb_cmd2

[Daniel Stone]

On Thu, 20 Jan 2022 at 12:48, Simon Ser <contact at emersion.fr> wrote:
> Follow-up for the DRM_IOCTL_MODE_GETFB2 docs.

Yeah, thanks a lot for doing this, it's really awesome. <3

> +/**
> + * 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).

I think the note about offsets[0] usually being zero should be
dropped. Equally, rather than referring to fourcc.org, why don't we
just refer to drm_fourcc.h and maybe note in there that fourcc.org can
be helpful for some formats, but others are missing or mismatching.

> +       /**
> +        * @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];

All these fields MBZ (not INVALID!) if the plane is unused.

Cheers,
Daniel