summaryrefslogtreecommitdiff
path: root/Documentation/DocBook
diff options
context:
space:
mode:
authorHans Verkuil <hans.verkuil@cisco.com>2012-09-03 09:37:18 -0300
committerMauro Carvalho Chehab <mchehab@redhat.com>2012-09-26 09:30:22 -0300
commit93828d6438081649e81b8681df9bf6ad5d691650 (patch)
tree0529d43509c1782b3e2f88a896e4540f408c2e87 /Documentation/DocBook
parent6bd4dd27f926519527b9c39709df13ad120d63f9 (diff)
[media] DocBook: make the G/S/TRY_FMT specification more strict
- S/TRY_FMT should always succeed, unless an invalid type field is passed in. - TRY_FMT should give the same result as S_FMT, all other things being equal. - ENUMFMT may return different formats for different inputs or outputs. This was decided during the 2012 Media Workshop. Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Reviewed-by: Sylwester Nawrocki <s.nawrocki@samsung.com> Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Sakari Ailus <sakari.ailus@iki.fi> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml3
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-fmt.xml9
2 files changed, 9 insertions, 3 deletions
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml
index 81ebe48317fe..0bd332421407 100644
--- a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml
@@ -58,6 +58,9 @@ structure. Drivers fill the rest of the structure or return an
incrementing by one until <errorcode>EINVAL</errorcode> is
returned.</para>
+ <para>Note that after switching input or output the list of enumerated image
+formats may be different.</para>
+
<table pgwide="1" frame="none" id="v4l2-fmtdesc">
<title>struct <structname>v4l2_fmtdesc</structname></title>
<tgroup cols="3">
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
index 52acff193a6f..b4b0e0a28545 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
@@ -81,7 +81,7 @@ the application calls the <constant>VIDIOC_S_FMT</constant> ioctl
with a pointer to a <structname>v4l2_format</structname> structure
the driver checks
and adjusts the parameters against hardware abilities. Drivers
-should not return an error code unless the input is ambiguous, this is
+should not return an error code unless the <structfield>type</structfield> field is invalid, this is
a mechanism to fathom device capabilities and to approach parameters
acceptable for both the application and driver. On success the driver
may program the hardware, allocate resources and generally prepare for
@@ -107,6 +107,10 @@ disabling I/O or possibly time consuming hardware preparations.
Although strongly recommended drivers are not required to implement
this ioctl.</para>
+ <para>The format as returned by <constant>VIDIOC_TRY_FMT</constant>
+must be identical to what <constant>VIDIOC_S_FMT</constant> returns for
+the same input or output.</para>
+
<table pgwide="1" frame="none" id="v4l2-format">
<title>struct <structname>v4l2_format</structname></title>
<tgroup cols="4">
@@ -187,8 +191,7 @@ capture and output devices.</entry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &v4l2-format; <structfield>type</structfield>
-field is invalid, the requested buffer type not supported, or the
-format is not supported with this buffer type.</para>
+field is invalid or the requested buffer type not supported.</para>
</listitem>
</varlistentry>
</variablelist>