| Message ID | 20220120124416.82202-1-contact@emersion.fr (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm: document struct drm_mode_fb_cmd2 | expand |
On Thu, Jan 20, 2022 at 1:48 PM Simon Ser <contact@emersion.fr> wrote: > > Follow-up for the DRM_IOCTL_MODE_GETFB2 docs. > > Signed-off-by: Simon Ser <contact@emersion.fr> > Cc: Daniel Vetter <daniel@ffwll.ch> > Cc: Pekka Paalanen <pekka.paalanen@collabora.com> > Cc: Daniel Stone <daniels@collabora.com> Thanks for pushing our docs forward! Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch> > --- > 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 > >
On Thu, 20 Jan 2022 at 12:48, Simon Ser <contact@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
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
Follow-up for the DRM_IOCTL_MODE_GETFB2 docs. Signed-off-by: Simon Ser <contact@emersion.fr> Cc: Daniel Vetter <daniel@ffwll.ch> Cc: Pekka Paalanen <pekka.paalanen@collabora.com> Cc: Daniel Stone <daniels@collabora.com> --- include/uapi/drm/drm_mode.h | 83 ++++++++++++++++++++++++------------- 1 file changed, 55 insertions(+), 28 deletions(-) base-commit: 37e0321ab2569b44f8a94339bf47653493ac864e