Replace the bare placeholder comment with a full kernel-doc block
documenting all parameters, the function behaviour for both single
memory plane (mem_planes == 1) and multiple memory plane (mem_planes > 1)
formats, and the return value.

Signed-off-by: Tommaso Merciai <tommaso.merciai.xr@bp.renesas.com>
---
v2->v3:
 - Moved to PATCH 3/4
 - Fixed documentation as suggested by Sven Püschel

v1->v2:
 - New patch

 include/media/v4l2-common.h | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
index be4dd9762196..f2b0c336ac81 100644
--- a/include/media/v4l2-common.h
+++ b/include/media/v4l2-common.h
@@ -591,7 +591,33 @@ static inline int v4l2_fill_pixfmt(struct v4l2_pix_format *pixfmt,
 	return v4l2_fill_pixfmt_aligned(pixfmt, pixelformat, width, height, 1);
 }
 
-/* @stride_alignment is a power of 2 value in bytes */
+/**
+ * v4l2_fill_pixfmt_mp_aligned - Fill in a &struct v4l2_pix_format_mplane with
+ *	stride alignment requirements.
+ *
+ * @pixfmt: pointer to the &struct v4l2_pix_format_mplane to be filled
+ * @pixelformat: the V4L2 pixel format (V4L2_PIX_FMT_*)
+ * @width: image width in pixels
+ * @height: image height in pixels
+ * @stride_alignment: stride alignment in bytes; must be a power of 2
+ *
+ * Fills all fields of @pixfmt for the given pixel format, dimensions, and
+ * stride alignment.
+ *
+ * For formats stored in a single memory plane (mem_planes == 1), the
+ * behaviour matches v4l2_fill_pixfmt_aligned(): plane_fmt[0].bytesperline
+ * is set to the primary plane stride. The strides of all components are
+ * aligned to the @stride_alignment. To keep the chroma strides consistently
+ * derivable from the luma stride, strides may be aligned to a multiple of
+ * the @stride_alignment instead. plane_fmt[0].sizeimage covers all
+ * component planes.
+ *
+ * For formats with multiple memory planes (mem_planes > 1), each plane's
+ * bytesperline is independently rounded up to @stride_alignment, and
+ * sizeimage is set to bytesperline multiplied by the plane height.
+ *
+ * Return: 0 on success, -EINVAL if @pixelformat is unknown.
+ */
 int v4l2_fill_pixfmt_mp_aligned(struct v4l2_pix_format_mplane *pixfmt,
 				u32 pixelformat, u32 width, u32 height,
 				u8 stride_alignment);
-- 
2.54.0

Hi Tommaso

On Wed, Jul 08, 2026 at 06:14:04PM +0200, Tommaso Merciai wrote:
> Replace the bare placeholder comment with a full kernel-doc block
> documenting all parameters, the function behaviour for both single
> memory plane (mem_planes == 1) and multiple memory plane (mem_planes > 1)
> formats, and the return value.
>
> Signed-off-by: Tommaso Merciai <tommaso.merciai.xr@bp.renesas.com>
> ---
> v2->v3:
>  - Moved to PATCH 3/4
>  - Fixed documentation as suggested by Sven Püschel
>
> v1->v2:
>  - New patch
>
>  include/media/v4l2-common.h | 28 +++++++++++++++++++++++++++-
>  1 file changed, 27 insertions(+), 1 deletion(-)
>
> diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
> index be4dd9762196..f2b0c336ac81 100644
> --- a/include/media/v4l2-common.h
> +++ b/include/media/v4l2-common.h
> @@ -591,7 +591,33 @@ static inline int v4l2_fill_pixfmt(struct v4l2_pix_format *pixfmt,
>  	return v4l2_fill_pixfmt_aligned(pixfmt, pixelformat, width, height, 1);
>  }
>
> -/* @stride_alignment is a power of 2 value in bytes */
> +/**
> + * v4l2_fill_pixfmt_mp_aligned - Fill in a &struct v4l2_pix_format_mplane with
> + *	stride alignment requirements.
> + *
> + * @pixfmt: pointer to the &struct v4l2_pix_format_mplane to be filled
> + * @pixelformat: the V4L2 pixel format (V4L2_PIX_FMT_*)
> + * @width: image width in pixels
> + * @height: image height in pixels
> + * @stride_alignment: stride alignment in bytes; must be a power of 2
> + *
> + * Fills all fields of @pixfmt for the given pixel format, dimensions, and
> + * stride alignment.
> + *
> + * For formats stored in a single memory plane (mem_planes == 1), the
> + * behaviour matches v4l2_fill_pixfmt_aligned(): plane_fmt[0].bytesperline
> + * is set to the primary plane stride. The strides of all components are
> + * aligned to the @stride_alignment. To keep the chroma strides consistently
> + * derivable from the luma stride, strides may be aligned to a multiple of
> + * the @stride_alignment instead. plane_fmt[0].sizeimage covers all


I guess this

"To keep the chroma strides consistently derivable from the luma
stride, strides may be aligned to a multiple of the @stride_alignment
instead."

comes from teh v4l2_format_plane_stride() implementation.

I admit is not 100% clear to me why the chroma strides is multiplied
and to which format this applies. But this is not on this patch...

> + * component planes.
> + *
> + * For formats with multiple memory planes (mem_planes > 1), each plane's
> + * bytesperline is independently rounded up to @stride_alignment, and

and each plane's sizeimage is ..

> + * sizeimage is set to bytesperline multiplied by the plane height.
> + *
> + * Return: 0 on success, -EINVAL if @pixelformat is unknown.
> + */

Reviewed-by: Jacopo Mondi <jacopo.mondi+renesas@ideasonboard.com>

Thanks
  j

>  int v4l2_fill_pixfmt_mp_aligned(struct v4l2_pix_format_mplane *pixfmt,
>  				u32 pixelformat, u32 width, u32 height,
>  				u8 stride_alignment);
> --
> 2.54.0
>
>

Hi Jacopo,

On 7/9/26 11:51 AM, Jacopo Mondi wrote:
> Hi Tommaso
>
> On Wed, Jul 08, 2026 at 06:14:04PM +0200, Tommaso Merciai wrote:
>> Replace the bare placeholder comment with a full kernel-doc block
>> documenting all parameters, the function behaviour for both single
>> memory plane (mem_planes == 1) and multiple memory plane (mem_planes > 1)
>> formats, and the return value.
>>
>> Signed-off-by: Tommaso Merciai <tommaso.merciai.xr@bp.renesas.com>
>> ---
>> v2->v3:
>>   - Moved to PATCH 3/4
>>   - Fixed documentation as suggested by Sven Püschel
>>
>> v1->v2:
>>   - New patch
>>
>>   include/media/v4l2-common.h | 28 +++++++++++++++++++++++++++-
>>   1 file changed, 27 insertions(+), 1 deletion(-)
>>
>> diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
>> index be4dd9762196..f2b0c336ac81 100644
>> --- a/include/media/v4l2-common.h
>> +++ b/include/media/v4l2-common.h
>> @@ -591,7 +591,33 @@ static inline int v4l2_fill_pixfmt(struct v4l2_pix_format *pixfmt,
>>   	return v4l2_fill_pixfmt_aligned(pixfmt, pixelformat, width, height, 1);
>>   }
>>
>> -/* @stride_alignment is a power of 2 value in bytes */
>> +/**
>> + * v4l2_fill_pixfmt_mp_aligned - Fill in a &struct v4l2_pix_format_mplane with
>> + *	stride alignment requirements.
>> + *
>> + * @pixfmt: pointer to the &struct v4l2_pix_format_mplane to be filled
>> + * @pixelformat: the V4L2 pixel format (V4L2_PIX_FMT_*)
>> + * @width: image width in pixels
>> + * @height: image height in pixels
>> + * @stride_alignment: stride alignment in bytes; must be a power of 2
>> + *
>> + * Fills all fields of @pixfmt for the given pixel format, dimensions, and
>> + * stride alignment.
>> + *
>> + * For formats stored in a single memory plane (mem_planes == 1), the
>> + * behaviour matches v4l2_fill_pixfmt_aligned(): plane_fmt[0].bytesperline
>> + * is set to the primary plane stride. The strides of all components are
>> + * aligned to the @stride_alignment. To keep the chroma strides consistently
>> + * derivable from the luma stride, strides may be aligned to a multiple of
>> + * the @stride_alignment instead. plane_fmt[0].sizeimage covers all
>
> I guess this
>
> "To keep the chroma strides consistently derivable from the luma
> stride, strides may be aligned to a multiple of the @stride_alignment
> instead."
>
> comes from teh v4l2_format_plane_stride() implementation.
>
> I admit is not 100% clear to me why the chroma strides is multiplied
> and to which format this applies. But this is not on this patch...

When not using multi-planar formats, we only have the stride value for 
the Y component and the other stride values are derived from it. This is 
the cause of this whole scaling.

E.g. for YUV420 4x2px picture, we have 4 bytes stride in the y plane and 
2 byte in the cb and cr plane. If we align the stride to 4 bytes (in all 
planes), we want both values to be a multiple of 4. As the cb/cr stride 
is derived from the y stride, we have to set the y stride to 8 bytes to 
get the desired 4 bytes stride in the cb/cr planes.

The rare case for scaling the component stride is NV24/42 (at least this 
is the only one I currently know of), where we actually have 4:4:4 
sub-sampling and have the cb/cr parts interleaved. So for a 1x2px 
picture we have 1 bytes in the y plane and 2 bytes in the c plane. To 
align to 4 bytes we need to set the c plane stride to 8 to be able to 
set the y plane stride to 4.


For multi-planar formats we have a separate stride for each component, 
so we just align all component strides to the given alignment.


Sincerely
     Sven

Hi Sven

On Fri, Jul 10, 2026 at 10:57:41AM +0200, Sven Püschel wrote:
> Hi Jacopo,
>
> On 7/9/26 11:51 AM, Jacopo Mondi wrote:
> > Hi Tommaso
> >
> > On Wed, Jul 08, 2026 at 06:14:04PM +0200, Tommaso Merciai wrote:
> > > Replace the bare placeholder comment with a full kernel-doc block
> > > documenting all parameters, the function behaviour for both single
> > > memory plane (mem_planes == 1) and multiple memory plane (mem_planes > 1)
> > > formats, and the return value.
> > >
> > > Signed-off-by: Tommaso Merciai <tommaso.merciai.xr@bp.renesas.com>
> > > ---
> > > v2->v3:
> > >   - Moved to PATCH 3/4
> > >   - Fixed documentation as suggested by Sven Püschel
> > >
> > > v1->v2:
> > >   - New patch
> > >
> > >   include/media/v4l2-common.h | 28 +++++++++++++++++++++++++++-
> > >   1 file changed, 27 insertions(+), 1 deletion(-)
> > >
> > > diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
> > > index be4dd9762196..f2b0c336ac81 100644
> > > --- a/include/media/v4l2-common.h
> > > +++ b/include/media/v4l2-common.h
> > > @@ -591,7 +591,33 @@ static inline int v4l2_fill_pixfmt(struct v4l2_pix_format *pixfmt,
> > >   	return v4l2_fill_pixfmt_aligned(pixfmt, pixelformat, width, height, 1);
> > >   }
> > >
> > > -/* @stride_alignment is a power of 2 value in bytes */
> > > +/**
> > > + * v4l2_fill_pixfmt_mp_aligned - Fill in a &struct v4l2_pix_format_mplane with
> > > + *	stride alignment requirements.
> > > + *
> > > + * @pixfmt: pointer to the &struct v4l2_pix_format_mplane to be filled
> > > + * @pixelformat: the V4L2 pixel format (V4L2_PIX_FMT_*)
> > > + * @width: image width in pixels
> > > + * @height: image height in pixels
> > > + * @stride_alignment: stride alignment in bytes; must be a power of 2
> > > + *
> > > + * Fills all fields of @pixfmt for the given pixel format, dimensions, and
> > > + * stride alignment.
> > > + *
> > > + * For formats stored in a single memory plane (mem_planes == 1), the
> > > + * behaviour matches v4l2_fill_pixfmt_aligned(): plane_fmt[0].bytesperline
> > > + * is set to the primary plane stride. The strides of all components are
> > > + * aligned to the @stride_alignment. To keep the chroma strides consistently
> > > + * derivable from the luma stride, strides may be aligned to a multiple of
> > > + * the @stride_alignment instead. plane_fmt[0].sizeimage covers all
> >
> > I guess this
> >
> > "To keep the chroma strides consistently derivable from the luma
> > stride, strides may be aligned to a multiple of the @stride_alignment
> > instead."
> >
> > comes from teh v4l2_format_plane_stride() implementation.
> >
> > I admit is not 100% clear to me why the chroma strides is multiplied
> > and to which format this applies. But this is not on this patch...
>
> When not using multi-planar formats, we only have the stride value for the Y
> component and the other stride values are derived from it. This is the cause
> of this whole scaling.
>
> E.g. for YUV420 4x2px picture, we have 4 bytes stride in the y plane and 2
> byte in the cb and cr plane. If we align the stride to 4 bytes (in all
> planes), we want both values to be a multiple of 4. As the cb/cr stride is
> derived from the y stride, we have to set the y stride to 8 bytes to get the
> desired 4 bytes stride in the cb/cr planes.
>
> The rare case for scaling the component stride is NV24/42 (at least this is
> the only one I currently know of), where we actually have 4:4:4 sub-sampling
> and have the cb/cr parts interleaved. So for a 1x2px picture we have 1 bytes
> in the y plane and 2 bytes in the c plane. To align to 4 bytes we need to
> set the c plane stride to 8 to be able to set the y plane stride to 4.

I see, I was probably confusing strides and strides -alignments-.

Thanks for the explanation.


>
>
> For multi-planar formats we have a separate stride for each component, so we
> just align all component strides to the given alignment.
>
>
> Sincerely
>     Sven
>
>