[PATCH] DocBook media: Clarify V4L2_FIELD_ANY for drivers

[PATCH] DocBook media: Clarify V4L2_FIELD_ANY for drivers

[Simon Farnsworth]

Documentation for enum v4l2_field did not make it clear that V4L2_FIELD_ANY
is only acceptable as input to the kernel, not as a response from the
driver.

Make it clear, to stop userspace developers like me assuming it can be
returned by the driver.

Signed-off-by: Simon Farnsworth <simon.farnsworth@onelan.co.uk>
---
 Documentation/DocBook/media/v4l/io.xml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
index e5e8325..8918bb2 100644
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -1422,7 +1422,10 @@ one of the <constant>V4L2_FIELD_NONE</constant>,
 <constant>V4L2_FIELD_BOTTOM</constant>, or
 <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
 Drivers choose depending on hardware capabilities or e.&nbsp;g. the
-requested image size, and return the actual field order. &v4l2-buffer;
+requested image size, and return the actual field order. If multiple
+field orders are possible the driver must choose one of the possible
+field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; and must not
+return V4L2_FIELD_ANY. &v4l2-buffer;
 <structfield>field</structfield> can never be
 <constant>V4L2_FIELD_ANY</constant>.</entry>
 	  </row>
-- 
1.9.3

Re: [PATCH] DocBook media: Clarify V4L2_FIELD_ANY for drivers

[Hans Verkuil]

On 10/31/2014 03:48 PM, Simon Farnsworth wrote:
> Documentation for enum v4l2_field did not make it clear that V4L2_FIELD_ANY
> is only acceptable as input to the kernel, not as a response from the
> driver.
> 
> Make it clear, to stop userspace developers like me assuming it can be
> returned by the driver.
> 
> Signed-off-by: Simon Farnsworth <simon.farnsworth@onelan.co.uk>
> ---
>  Documentation/DocBook/media/v4l/io.xml | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
> index e5e8325..8918bb2 100644
> --- a/Documentation/DocBook/media/v4l/io.xml
> +++ b/Documentation/DocBook/media/v4l/io.xml
> @@ -1422,7 +1422,10 @@ one of the <constant>V4L2_FIELD_NONE</constant>,
>  <constant>V4L2_FIELD_BOTTOM</constant>, or
>  <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
>  Drivers choose depending on hardware capabilities or e.&nbsp;g. the
> -requested image size, and return the actual field order. &v4l2-buffer;
> +requested image size, and return the actual field order. If multiple
> +field orders are possible the driver must choose one of the possible
> +field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; and must not
> +return V4L2_FIELD_ANY. &v4l2-buffer;

I would phrase it slightly differently:

"Drivers must never return <constant>V4L2_FIELD_ANY</constant>. If multiple
field orders are possible the driver must choose one of the possible
field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;."

Regards,

	Hans

>  <structfield>field</structfield> can never be
>  <constant>V4L2_FIELD_ANY</constant>.</entry>
>  	  </row>
> 

Re: [PATCH] DocBook media: Clarify V4L2_FIELD_ANY for drivers

[Simon Farnsworth]

[-- Attachment #1: Type: text/plain, Size: 1835 bytes --]

On Friday 31 October 2014 15:54:01 Hans Verkuil wrote:
> On 10/31/2014 03:48 PM, Simon Farnsworth wrote:
> > Documentation for enum v4l2_field did not make it clear that V4L2_FIELD_ANY
> > is only acceptable as input to the kernel, not as a response from the
> > driver.
> > 
> > Make it clear, to stop userspace developers like me assuming it can be
> > returned by the driver.
> > 
> > Signed-off-by: Simon Farnsworth <simon.farnsworth@onelan.co.uk>
> > ---
> >  Documentation/DocBook/media/v4l/io.xml | 5 ++++-
> >  1 file changed, 4 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
> > index e5e8325..8918bb2 100644
> > --- a/Documentation/DocBook/media/v4l/io.xml
> > +++ b/Documentation/DocBook/media/v4l/io.xml
> > @@ -1422,7 +1422,10 @@ one of the <constant>V4L2_FIELD_NONE</constant>,
> >  <constant>V4L2_FIELD_BOTTOM</constant>, or
> >  <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
> >  Drivers choose depending on hardware capabilities or e.&nbsp;g. the
> > -requested image size, and return the actual field order. &v4l2-buffer;
> > +requested image size, and return the actual field order. If multiple
> > +field orders are possible the driver must choose one of the possible
> > +field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; and must not
> > +return V4L2_FIELD_ANY. &v4l2-buffer;
> 
> I would phrase it slightly differently:
> 
> "Drivers must never return <constant>V4L2_FIELD_ANY</constant>. If multiple
> field orders are possible the driver must choose one of the possible
> field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;."
> 

I like your wording better than mine. v2 patch sent.

-- 
Simon Farnsworth
Software Engineer
ONELAN Ltd
http://www.onelan.com

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 473 bytes --]