Re: [PATCH 2/3] media: videodev2.h: clarify v4l2_pix_format_mplane.sizeimage docs when to set to zero

[Helen Koike <helen.koike@collabora.com>]

On 1/25/21 6:31 AM, Hans Verkuil wrote:
> On 14/01/2021 19:01, Helen Koike wrote:
>> sizeimage field should be set to zero for unused planes, even when
>> v4l2_pix_format_mplane.num_planes is smaller then the index of planes.
> 
> then -> than

Ack.

> 
>>
>> Signed-off-by: Helen Koike <helen.koike@collabora.com>
>>
>> ---
>>
>> I caught this with v4l2-compliance, which throws an error if we dirty
>> planes, even if invalid, so I would like to make it clear in the docs.
> 
> What is the error? And with which driver?

I was implementing conversions to/from Ext API, and I thought v4l2-compliance
wasn't happy if I didn't zero the other entries, but I'm trying to reproduce
it now by adding a non-zero value to sizeimage and I can't reproduce it, so
it was probably my mistake.
Please ignore this patch and sorry for the noise.

> 
> I wonder if this isn't a v4l2-compliance bug. And if we want this to be
> zeroed, then it wouldn't it be better to do that in the V4L2 core rather
> than bother drivers with this?
> 
>> ---
>>  include/uapi/linux/videodev2.h | 1 +
>>  1 file changed, 1 insertion(+)
>>
>> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
>> index 79dbde3bcf8d..d9b7c9177605 100644
>> --- a/include/uapi/linux/videodev2.h
>> +++ b/include/uapi/linux/videodev2.h
>> @@ -2227,6 +2227,7 @@ struct v4l2_mpeg_vbi_fmt_ivtv {
>>   * struct v4l2_plane_pix_format - additional, per-plane format definition
>>   * @sizeimage:		maximum size in bytes required for data, for which
>>   *			this plane will be used
>> + *			Drivers should be set it zero for unused planes.
> 
> This sentence is a bit garbled.
> 
> You probably meant: Drivers must set this to zero for unused planes.
> 
> But it makes no sense to just zero this field. I would zero the whole struct
> contents for the unused planes.
> 
>>   * @bytesperline:	distance in bytes between the leftmost pixels in two
>>   *			adjacent lines
>>   */
>>
> 
> The API doesn't mention whether unused plane formats should be zeroed or not,
> but it does make sense that they are. I don't think that the userspace API
> should be changed (esp. since there are apparently already drivers that do
> not zero these unused plane formats), but it makes sense that the compliance
> test does verify this, and that the V4L2 core would zero unused plane formats.
> 
> I never like it when undefined values are allowed in an API, so it makes sense
> that this is done.


Ack.

Thanks
Helen


> 
> Regards,
> 
> 	Hans
>