[PATCH v2] V4L2: Add documentation for SDI timings and related flags

[PATCH v2] V4L2: Add documentation for SDI timings and related flags

[Charles-Antoine Couret]

Signed-off-by: Charles-Antoine Couret <charles-antoine.couret@nexvision.fr>
---
 Documentation/media/uapi/v4l/vidioc-enuminput.rst  | 31 +++++++++++++++++-----
 .../media/uapi/v4l/vidioc-g-dv-timings.rst         | 16 +++++++++++
 2 files changed, 40 insertions(+), 7 deletions(-)

diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
index 5060f54..18331b9 100644
--- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
@@ -260,17 +260,34 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
 
     -  .. row 11
 
-       -  :cspan:`2` Digital Video
+       -  ``V4L2_IN_ST_NO_V_LOCK``
+
+       -  0x00000400
+
+       -  No vertical sync lock.
 
     -  .. row 12
 
+       -  ``V4L2_IN_ST_NO_STD_LOCK``
+
+       -  0x00000800
+
+       -  No standard format lock in case of auto-detection format
+	  by the component.
+
+    -  .. row 13
+
+       -  :cspan:`2` Digital Video
+
+    -  .. row 14
+
        -  ``V4L2_IN_ST_NO_SYNC``
 
        -  0x00010000
 
        -  No synchronization lock.
 
-    -  .. row 13
+    -  .. row 15
 
        -  ``V4L2_IN_ST_NO_EQU``
 
@@ -278,7 +295,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
 
        -  No equalizer lock.
 
-    -  .. row 14
+    -  .. row 16
 
        -  ``V4L2_IN_ST_NO_CARRIER``
 
@@ -286,11 +303,11 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
 
        -  Carrier recovery failed.
 
-    -  .. row 15
+    -  .. row 17
 
        -  :cspan:`2` VCR and Set-Top Box
 
-    -  .. row 16
+    -  .. row 18
 
        -  ``V4L2_IN_ST_MACROVISION``
 
@@ -300,7 +317,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
 	  signal to confuse video recorders. When this flag is set
 	  Macrovision has been detected.
 
-    -  .. row 17
+    -  .. row 19
 
        -  ``V4L2_IN_ST_NO_ACCESS``
 
@@ -308,7 +325,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
 
        -  Conditional access denied.
 
-    -  .. row 18
+    -  .. row 20
 
        -  ``V4L2_IN_ST_VTR``
 
diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
index f7bf21f..0205bf6 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
@@ -339,6 +339,14 @@ EBUSY
 
        -  The timings follow the VESA Generalized Timings Formula standard
 
+    -  .. row 7
+
+       -  ``V4L2_DV_BT_STD_SDI``
+
+       -  The timings follow the SDI Timings standard.
+	  There are not always horizontal syncs/porches or similar in this format.
+	  If it is not precised by standard, blanking timings must be set in
+	  hsync or vsync fields by default.
 
 
 .. _dv-bt-flags:
@@ -415,3 +423,11 @@ EBUSY
 	  R'G'B' values use limited range (i.e. 16-235) as opposed to full
 	  range (i.e. 0-255). All formats defined in CEA-861 except for the
 	  640x480p59.94 format are CE formats.
+
+    -  .. row 8
+
+       -  ``V4L2_DV_FL_FIRST_FIELD_EXTRA_LINE``
+
+       -  Some formats like SMPTE-125M have an interlaced signal with a odd
+	  total height. For these formats, if this flag is set, the first
+	  field has the extra line. Else, it is the second field.
-- 
2.7.4

Re: [PATCH v2] V4L2: Add documentation for SDI timings and related flags

[Markus Heiser]

Am 04.08.2016 um 17:39 schrieb Charles-Antoine Couret <charles-antoine.couret@nexvision.fr>:

> Signed-off-by: Charles-Antoine Couret <charles-antoine.couret@nexvision.fr>
> ---
> Documentation/media/uapi/v4l/vidioc-enuminput.rst  | 31 +++++++++++++++++-----
> .../media/uapi/v4l/vidioc-g-dv-timings.rst         | 16 +++++++++++
> 2 files changed, 40 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
> index 5060f54..18331b9 100644
> --- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
> @@ -260,17 +260,34 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
> 
>    -  .. row 11
> 
> -       -  :cspan:`2` Digital Video
> +       -  ``V4L2_IN_ST_NO_V_LOCK``
> +
> +       -  0x00000400
> +
> +       -  No vertical sync lock.
> 
>    -  .. row 12
> 
> +       -  ``V4L2_IN_ST_NO_STD_LOCK``
> +
> +       -  0x00000800
> +
> +       -  No standard format lock in case of auto-detection format
> +	  by the component.
> +
> +    -  .. row 13
> +
> +       -  :cspan:`2` Digital Video
> +
> +    -  .. row 14
> +
>       -  ``V4L2_IN_ST_NO_SYNC``
> 
>       -  0x00010000
> 
>       -  No synchronization lock.
> 
> -    -  .. row 13
> +    -  .. row 15

Hi Charles,

you don't need to continue the "row nn" comments. These row-numbering 
comes from the migration tool when we migrated from DocBook.

@Mauro: may it is the best, we drop all these "row nn" comments?

-- Markus --

Re: [PATCH v2] V4L2: Add documentation for SDI timings and related flags

[Mauro Carvalho Chehab]

Em Thu, 4 Aug 2016 18:04:50 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 04.08.2016 um 17:39 schrieb Charles-Antoine Couret <charles-antoine.couret@nexvision.fr>:
> 
> > Signed-off-by: Charles-Antoine Couret <charles-antoine.couret@nexvision.fr>
> > ---
> > Documentation/media/uapi/v4l/vidioc-enuminput.rst  | 31 +++++++++++++++++-----
> > .../media/uapi/v4l/vidioc-g-dv-timings.rst         | 16 +++++++++++
> > 2 files changed, 40 insertions(+), 7 deletions(-)
> > 
> > diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
> > index 5060f54..18331b9 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
> > @@ -260,17 +260,34 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
> > 
> >    -  .. row 11
> > 
> > -       -  :cspan:`2` Digital Video
> > +       -  ``V4L2_IN_ST_NO_V_LOCK``
> > +
> > +       -  0x00000400
> > +
> > +       -  No vertical sync lock.
> > 
> >    -  .. row 12
> > 
> > +       -  ``V4L2_IN_ST_NO_STD_LOCK``
> > +
> > +       -  0x00000800
> > +
> > +       -  No standard format lock in case of auto-detection format
> > +	  by the component.
> > +
> > +    -  .. row 13
> > +
> > +       -  :cspan:`2` Digital Video
> > +
> > +    -  .. row 14
> > +
> >       -  ``V4L2_IN_ST_NO_SYNC``
> > 
> >       -  0x00010000
> > 
> >       -  No synchronization lock.
> > 
> > -    -  .. row 13
> > +    -  .. row 15  
> 
> Hi Charles,
> 
> you don't need to continue the "row nn" comments. These row-numbering 
> comes from the migration tool when we migrated from DocBook.
> 
> @Mauro: may it is the best, we drop all these "row nn" comments?

For now, let's just keep it. I'll address it later. On several
tables, the best way would actually to replace the "row \d" comment
by a reference, like:

    -  .. _v4l2-in-st-no-sync:

      -  ``V4L2_IN_ST_NO_SYNC``

      -  0x00010000


and then fix the cross-references at the videodev2.h file, removing
the exceptions at the videodev2.h.rst.exceptions file.

I intend to take care of it for 4.9.

-- 
Thanks,
Mauro

Re: [PATCH v2] V4L2: Add documentation for SDI timings and related flags

[Hans Verkuil]

On 08/04/2016 05:39 PM, Charles-Antoine Couret wrote:

A commit log is missing here.

> Signed-off-by: Charles-Antoine Couret <charles-antoine.couret@nexvision.fr>
> ---
>  Documentation/media/uapi/v4l/vidioc-enuminput.rst  | 31 +++++++++++++++++-----
>  .../media/uapi/v4l/vidioc-g-dv-timings.rst         | 16 +++++++++++
>  2 files changed, 40 insertions(+), 7 deletions(-)
> 

<snip>

> diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> index f7bf21f..0205bf6 100644
> --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> @@ -339,6 +339,14 @@ EBUSY
>  
>         -  The timings follow the VESA Generalized Timings Formula standard
>  
> +    -  .. row 7
> +
> +       -  ``V4L2_DV_BT_STD_SDI``
> +
> +       -  The timings follow the SDI Timings standard.
> +	  There are not always horizontal syncs/porches or similar in this format.
> +	  If it is not precised by standard, blanking timings must be set in
> +	  hsync or vsync fields by default.

OK. This is confusing. The text was changed after my question about something porch-like
in the SMPTE-125M standard. But I see nothing like that after re-reading it.

So what sort of 'porch' timing were you thinking of?

I wonder if I shouldn't just use the text from your first patch:

       -  ``V4L2_DV_BT_STD_SDI``

       -  The timings follow the SDI Timings standard.
	  There are no horizontal syncs/porches at all in this format.
	  Total blanking timings must be set in hsync or vsync fields only.

Regards,

	Hans

Re: [PATCH v2] V4L2: Add documentation for SDI timings and related flags

[Charles-Antoine Couret]

Le 12/08/2016 à 15:17, Hans Verkuil a écrit :
> On 08/04/2016 05:39 PM, Charles-Antoine Couret wrote:
> 
> A commit log is missing here.

Yeah I will fix that.

>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
>> index f7bf21f..0205bf6 100644
>> --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
>> +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
>> @@ -339,6 +339,14 @@ EBUSY
>>  
>>         -  The timings follow the VESA Generalized Timings Formula standard
>>  
>> +    -  .. row 7
>> +
>> +       -  ``V4L2_DV_BT_STD_SDI``
>> +
>> +       -  The timings follow the SDI Timings standard.
>> +	  There are not always horizontal syncs/porches or similar in this format.
>> +	  If it is not precised by standard, blanking timings must be set in
>> +	  hsync or vsync fields by default.
> 
> OK. This is confusing. The text was changed after my question about something porch-like
> in the SMPTE-125M standard. But I see nothing like that after re-reading it.
> 
> So what sort of 'porch' timing were you thinking of?

In SMPTE-125M for example, the time between the real horizontal blanking is precised (16 pixelclock).
For me it looks like front porch timing.
 
> I wonder if I shouldn't just use the text from your first patch:
> 
>        -  ``V4L2_DV_BT_STD_SDI``
> 
>        -  The timings follow the SDI Timings standard.
> 	  There are no horizontal syncs/porches at all in this format.
> 	  Total blanking timings must be set in hsync or vsync fields only.

I agree with that if you prefer, after all the front/backporch are probably irrelevant in this case.
So, if you confirm this way, I would send you another patchset to fix that.

Thank you.
Regards,
Charles-Antoine Couret

Re: [PATCH v2] V4L2: Add documentation for SDI timings and related flags

[Hans Verkuil]

On 09/07/2016 11:26 AM, Charles-Antoine Couret wrote:
> Le 12/08/2016 à 15:17, Hans Verkuil a écrit :
>> On 08/04/2016 05:39 PM, Charles-Antoine Couret wrote:
>>
>> A commit log is missing here.
> 
> Yeah I will fix that.
> 
>>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
>>> index f7bf21f..0205bf6 100644
>>> --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
>>> +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
>>> @@ -339,6 +339,14 @@ EBUSY
>>>  
>>>         -  The timings follow the VESA Generalized Timings Formula standard
>>>  
>>> +    -  .. row 7
>>> +
>>> +       -  ``V4L2_DV_BT_STD_SDI``
>>> +
>>> +       -  The timings follow the SDI Timings standard.
>>> +	  There are not always horizontal syncs/porches or similar in this format.
>>> +	  If it is not precised by standard, blanking timings must be set in
>>> +	  hsync or vsync fields by default.
>>
>> OK. This is confusing. The text was changed after my question about something porch-like
>> in the SMPTE-125M standard. But I see nothing like that after re-reading it.
>>
>> So what sort of 'porch' timing were you thinking of?
> 
> In SMPTE-125M for example, the time between the real horizontal blanking is precised (16 pixelclock).
> For me it looks like front porch timing.

Well, for some variants it is actually half-timings (21.5). In addition, it doesn't
seem to be used at all, it is just to relate the analog hsync to the digital sample.

>> I wonder if I shouldn't just use the text from your first patch:
>>
>>        -  ``V4L2_DV_BT_STD_SDI``
>>
>>        -  The timings follow the SDI Timings standard.
>> 	  There are no horizontal syncs/porches at all in this format.
>> 	  Total blanking timings must be set in hsync or vsync fields only.
> 
> I agree with that if you prefer, after all the front/backporch are probably irrelevant in this case.
> So, if you confirm this way, I would send you another patchset to fix that.

I think we should stick to this text.

Regards,

	Hans