Questions regarding Documentation/media/uapi/v4l/field-order.rst

[Rodin, Michael (Ferchau; ADITG/ESM1)]

Hi,

I would like to ask several questions regarding the documentation of the enum "v4l2_field" [1].
These questions came up during my investigations of issues with interaction between
the gstreamer plugin v4l2src and the rcar video input driver [2].

The documentation [1] specifies that:
"All video capture and output devices must report the current field order.
Some drivers may permit the selection of a different order, to this end
applications initialize the field field of struct v4l2_pix_format before
calling the VIDIOC_S_FMT ioctl. If this is not desired it should have
the value V4L2_FIELD_ANY (0)."

If I have understood these lines correctly, this means that if userspace sets "field" member of
the struct "v4l2_pix_format" to V4L2_FIELD_ANY and uses this as parameter for the VIDIOC_S_FMT ioctl,
then a driver should select/report the field order, which was previously set by media-ctl utility
in the next subdevice, which is connected to the /dev/videoX node
(From my understanding this would be equivalent to the "current field order").

If the described behavior is correct, then the description in the table row for V4L2_FIELD_ANY in [1] is incomplete:
"Applications request this field order when any one of the V4L2_FIELD_NONE, V4L2_FIELD_TOP, V4L2_FIELD_BOTTOM, or V4L2_FIELD_INTERLACED formats is acceptable."
What if V4L2_FIELD_ALTERNATE or V4L2_FIELD_SEQ_TB or V4L2_FIELD_SEQ_BT are also acceptable for the application?
I think that the specification is either unprecise or my understanding of the specification is wrong.

Another potential issue, which I found in this documentation is that it does not distinguish between
multiple contexts in which enum v4l2_field can be used. I can think of at least two different contexts:
- When used to select the field order with VIDIOC_S_FMT ioctl.
- When used to report the field order in a buffer: for example application sets V4L2_FIELD_ALTERNATE in VIDIOC_S_FMT ioctl and then gets buffers, which have V4L2_FIELD_TOP/BOTTOM set.
Now with this in mind, when I read the description of V4L2_FIELD_NONE:
"The driver may also indicate this order when it cannot distinguish between V4L2_FIELD_TOP and V4L2_FIELD_BOTTOM."
I see two possible meanings/interpretations:
- If application sets V4L2_FIELD_ALTERNATE in VIDIOC_S_FMT ioctl, report V4L2_FIELD_NONE back
   so the application knows that the driver can not provide any TOP/BOTTOM metadata in the buffers
   (which may be necessary for the application for example for deinterlacing) before it has got any buffer.
- If application sets V4L2_FIELD_ALTERNATE in VIDIOC_S_FMT ioctl, driver reports V4L2_FIELD_ALTERNATE back,
   even if it can not distinguish between TOP/BOTTOM. But when the application starts to read buffers,
   they have V4L2_FIELD_NONE set if it's not possible to distinguish between TOP/BOTTOM.

Also there is another ambiguity in the description of V4L2_FIELD_NONE:
"Images are in progressive format, not interlaced."
What does "interlaced" mean in this case? Does it mean the other possible enum values or just the V4L2_FIELD_INTERLACED?
If this just means V4L2_FIELD_INTERLACED, then it would imply that for example V4L2_FIELD_SEQ_TB 
and V4L2_FIELD_ALTERNATE are progressive formats, which is obviously not true.
And also generally, in which of described contexts should be V4L2_FIELD_NONE set or reported (buffer or VIDIOC_S_FMT ioctl)?
Another point is that V4L2_FIELD_INTERLACED is also used by v4l2src to tell rcar-vin driver to combine the fields before giving them to application,
so basically it requests progressive signal. So the meanings of V4L2_FIELD_INTERLACED and V4L2_FIELD_NONE are basically the same in this case.

Thank you in advance and sorry for the long mail!

[1] Documentation/media/uapi/v4l/field-order.rst
[2] drivers/media/platform/rcar-vin

Best regards

Michael Rodin

Advanced Driver Information Technology GmbH
Engineering Software Multimedia 1 (ADITG/ESM1)
Robert-Bosch-Str. 200
31139 Hildesheim
Germany

Tel. +49 5121 49 6936
Fax +49 5121 49 6999
mrodin@xxxxxxxxxxxxxx
Web: www.adit-jv.com

ADIT is a joint venture company of Robert Bosch GmbH/Robert Bosch Car Multimedia GmbH and DENSO Corporation
Sitz: Hildesheim, Registergericht: Amtsgericht Hildesheim HRB 3438
Geschaeftsfuehrung: Wilhelm Grabow, Ken Yaguchi