[PATCH 0/3] EDID/DV_TIMINGS docbook fixes

[PATCH 0/3] EDID/DV_TIMINGS docbook fixes

[Hans Verkuil]

Fixes a few issues I found in the documentation.

Hans Verkuil (3):
  vidioc-g-edid.xml: be explicit about zeroing the reserved array
  vidioc-enum-dv-timings.xml: explicitly state that pad and reserved
    should be zeroed
  vidioc-dv-timings-cap.xml: explicitly state that pad and reserved
    should be zeroed

 Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml  | 12 +++++++-----
 Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml |  5 +++--
 Documentation/DocBook/media/v4l/vidioc-g-edid.xml          | 10 ++++++----
 3 files changed, 16 insertions(+), 11 deletions(-)

-- 
2.7.0

[PATCH 1/3] vidioc-g-edid.xml: be explicit about zeroing the reserved array

[Hans Verkuil]

The G/S_EDID documentation did not explicitly state that the reserved array
should be zeroed by the application.

Also add the missing VIDIOC_SUBDEV_G/S_EDID ioctl names to the header.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
---
 Documentation/DocBook/media/v4l/vidioc-g-edid.xml | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/DocBook/media/v4l/vidioc-g-edid.xml b/Documentation/DocBook/media/v4l/vidioc-g-edid.xml
index 2702536..b7602d3 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-edid.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-edid.xml
@@ -1,6 +1,6 @@
 <refentry id="vidioc-g-edid">
   <refmeta>
-    <refentrytitle>ioctl VIDIOC_G_EDID, VIDIOC_S_EDID</refentrytitle>
+    <refentrytitle>ioctl VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID</refentrytitle>
     &manvol;
   </refmeta>
 
@@ -71,7 +71,8 @@
 
     <para>To get the EDID data the application has to fill in the <structfield>pad</structfield>,
     <structfield>start_block</structfield>, <structfield>blocks</structfield> and <structfield>edid</structfield>
-    fields and call <constant>VIDIOC_G_EDID</constant>. The current EDID from block
+    fields, zero the <structfield>reserved</structfield> array and call
+    <constant>VIDIOC_G_EDID</constant>. The current EDID from block
     <structfield>start_block</structfield> and of size <structfield>blocks</structfield>
     will be placed in the memory <structfield>edid</structfield> points to. The <structfield>edid</structfield>
     pointer must point to memory at least <structfield>blocks</structfield>&nbsp;*&nbsp;128 bytes
@@ -92,8 +93,9 @@
     the driver will set <structfield>blocks</structfield> to 0 and it returns 0.</para>
 
     <para>To set the EDID blocks of a receiver the application has to fill in the <structfield>pad</structfield>,
-    <structfield>blocks</structfield> and <structfield>edid</structfield> fields and set
-    <structfield>start_block</structfield> to 0. It is not possible to set part of an EDID,
+    <structfield>blocks</structfield> and <structfield>edid</structfield> fields, set
+    <structfield>start_block</structfield> to 0 and zero the <structfield>reserved</structfield> array.
+    It is not possible to set part of an EDID,
     it is always all or nothing. Setting the EDID data is only valid for receivers as it makes
     no sense for a transmitter.</para>
 
-- 
2.7.0

[PATCH 2/3] vidioc-enum-dv-timings.xml: explicitly state that pad and reserved should be zeroed

[Hans Verkuil]

The ENUM_DV_TIMINGS documentation did not clearly state that the pad and reserved
fields should be zeroed (pad only when used with a video device node).

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
---
 Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
index 6e3cadd..70ca76d 100644
--- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
@@ -61,8 +61,9 @@ of known supported timings. Call &VIDIOC-DV-TIMINGS-CAP; to check if it also sup
 standards or even custom timings that are not in this list.</para>
 
     <para>To query the available timings, applications initialize the
-<structfield>index</structfield> field and zero the reserved array of &v4l2-enum-dv-timings;
-and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl on a video node with a
+<structfield>index</structfield> field, set the <structfield>pad</structfield> field to 0,
+zero the reserved array of &v4l2-enum-dv-timings; and call the
+<constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl on a video node with a
 pointer to this structure. Drivers fill the rest of the structure or return an
 &EINVAL; when the index is out of bounds. To enumerate all supported DV timings,
 applications shall begin at index zero, incrementing by one until the
-- 
2.7.0

[PATCH 3/3] vidioc-dv-timings-cap.xml: explicitly state that pad and reserved should be zeroed

[Hans Verkuil]

The DV_TIMINGS_CAP documentation didn't state clearly that the pad and
reserved fields should be zeroed by the application. For subdev pad can
be other values as well.

It also mistakenly said that only drivers would have to zero the reserved
field, that's not correct.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
---
 Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
index a2017bf..b6f47a6 100644
--- a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
@@ -55,8 +55,9 @@
       interface and may change in the future.</para>
     </note>
 
-    <para>To query the capabilities of the DV receiver/transmitter applications
-can call the <constant>VIDIOC_DV_TIMINGS_CAP</constant> ioctl on a video node
+    <para>To query the capabilities of the DV receiver/transmitter applications initialize the
+<structfield>pad</structfield> field to 0, zero the reserved array of &v4l2-dv-timings-cap;
+and call the <constant>VIDIOC_DV_TIMINGS_CAP</constant> ioctl on a video node
 and the driver will fill in the structure. Note that drivers may return
 different values after switching the video input or output.</para>
 
@@ -65,8 +66,8 @@ queried by calling the <constant>VIDIOC_SUBDEV_DV_TIMINGS_CAP</constant> ioctl
 directly on a subdevice node. The capabilities are specific to inputs (for DV
 receivers) or outputs (for DV transmitters), applications must specify the
 desired pad number in the &v4l2-dv-timings-cap; <structfield>pad</structfield>
-field. Attempts to query capabilities on a pad that doesn't support them will
-return an &EINVAL;.</para>
+field and zero the <structfield>reserved</structfield> array. Attempts to query
+capabilities on a pad that doesn't support them will return an &EINVAL;.</para>
 
     <table pgwide="1" frame="none" id="v4l2-bt-timings-cap">
       <title>struct <structname>v4l2_bt_timings_cap</structname></title>
@@ -145,7 +146,8 @@ return an &EINVAL;.</para>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>reserved</structfield>[2]</entry>
-	    <entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
+	    <entry>Reserved for future extensions. Drivers and applications must
+	    set the array to zero.</entry>
 	  </row>
 	  <row>
 	    <entry>union</entry>
-- 
2.7.0

Re: [PATCH 0/3] EDID/DV_TIMINGS docbook fixes

[Sakari Ailus]

On Tue, Mar 22, 2016 at 11:30:26AM +0100, Hans Verkuil wrote:
> Fixes a few issues I found in the documentation.
> 
> Hans Verkuil (3):
>   vidioc-g-edid.xml: be explicit about zeroing the reserved array
>   vidioc-enum-dv-timings.xml: explicitly state that pad and reserved
>     should be zeroed
>   vidioc-dv-timings-cap.xml: explicitly state that pad and reserved
>     should be zeroed
> 
>  Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml  | 12 +++++++-----
>  Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml |  5 +++--
>  Documentation/DocBook/media/v4l/vidioc-g-edid.xml          | 10 ++++++----
>  3 files changed, 16 insertions(+), 11 deletions(-)

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi	XMPP: sailus@retiisi.org.uk