ARM: 7409/1: Do not call flush_cache_user_range with mmap_sem held
[linux/fpc-iii.git] / Documentation / DocBook / v4l / vidioc-subdev-enum-frame-interval.xml
blob2f8f4f0a023596c5b75d0ec22e8ce3d1be9ae350
1 <refentry id="vidioc-subdev-enum-frame-interval">
2   <refmeta>
3     <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refentrytitle>
4     &manvol;
5   </refmeta>
7   <refnamediv>
8     <refname>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refname>
9     <refpurpose>Enumerate frame intervals</refpurpose>
10   </refnamediv>
12   <refsynopsisdiv>
13     <funcsynopsis>
14       <funcprototype>
15         <funcdef>int <function>ioctl</function></funcdef>
16         <paramdef>int <parameter>fd</parameter></paramdef>
17         <paramdef>int <parameter>request</parameter></paramdef>
18         <paramdef>struct v4l2_subdev_frame_interval_enum *
19         <parameter>argp</parameter></paramdef>
20       </funcprototype>
21     </funcsynopsis>
22   </refsynopsisdiv>
24   <refsect1>
25     <title>Arguments</title>
27     <variablelist>
28       <varlistentry>
29         <term><parameter>fd</parameter></term>
30         <listitem>
31           <para>&fd;</para>
32         </listitem>
33       </varlistentry>
34       <varlistentry>
35         <term><parameter>request</parameter></term>
36         <listitem>
37           <para>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</para>
38         </listitem>
39       </varlistentry>
40       <varlistentry>
41         <term><parameter>argp</parameter></term>
42         <listitem>
43           <para></para>
44         </listitem>
45       </varlistentry>
46     </variablelist>
47   </refsect1>
49   <refsect1>
50     <title>Description</title>
52     <note>
53       <title>Experimental</title>
54       <para>This is an <link linkend="experimental">experimental</link>
55       interface and may change in the future.</para>
56     </note>
58     <para>This ioctl lets applications enumerate available frame intervals on a
59     given sub-device pad. Frame intervals only makes sense for sub-devices that
60     can control the frame period on their own. This includes, for instance,
61     image sensors and TV tuners.</para>
63     <para>For the common use case of image sensors, the frame intervals
64     available on the sub-device output pad depend on the frame format and size
65     on the same pad. Applications must thus specify the desired format and size
66     when enumerating frame intervals.</para>
68     <para>To enumerate frame intervals applications initialize the
69     <structfield>index</structfield>, <structfield>pad</structfield>,
70     <structfield>code</structfield>, <structfield>width</structfield> and
71     <structfield>height</structfield> fields of
72     &v4l2-subdev-frame-interval-enum; and call the
73     <constant>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</constant> ioctl with a pointer
74     to this structure. Drivers fill the rest of the structure or return
75     an &EINVAL; if one of the input fields is invalid. All frame intervals are
76     enumerable by beginning at index zero and incrementing by one until
77     <errorcode>EINVAL</errorcode> is returned.</para>
79     <para>Available frame intervals may depend on the current 'try' formats
80     at other pads of the sub-device, as well as on the current active links. See
81     &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para>
83     <para>Sub-devices that support the frame interval enumeration ioctl should
84     implemented it on a single pad only. Its behaviour when supported on
85     multiple pads of the same sub-device is not defined.</para>
87     <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval-enum">
88       <title>struct <structname>v4l2_subdev_frame_interval_enum</structname></title>
89       <tgroup cols="3">
90         &cs-str;
91         <tbody valign="top">
92           <row>
93             <entry>__u32</entry>
94             <entry><structfield>index</structfield></entry>
95             <entry>Number of the format in the enumeration, set by the
96             application.</entry>
97           </row>
98           <row>
99             <entry>__u32</entry>
100             <entry><structfield>pad</structfield></entry>
101             <entry>Pad number as reported by the media controller API.</entry>
102           </row>
103           <row>
104             <entry>__u32</entry>
105             <entry><structfield>code</structfield></entry>
106             <entry>The media bus format code, as defined in
107             <xref linkend="v4l2-mbus-format" />.</entry>
108           </row>
109           <row>
110             <entry>__u32</entry>
111             <entry><structfield>width</structfield></entry>
112             <entry>Frame width, in pixels.</entry>
113           </row>
114           <row>
115             <entry>__u32</entry>
116             <entry><structfield>height</structfield></entry>
117             <entry>Frame height, in pixels.</entry>
118           </row>
119           <row>
120             <entry>&v4l2-fract;</entry>
121             <entry><structfield>interval</structfield></entry>
122             <entry>Period, in seconds, between consecutive video frames.</entry>
123           </row>
124           <row>
125             <entry>__u32</entry>
126             <entry><structfield>reserved</structfield>[9]</entry>
127             <entry>Reserved for future extensions. Applications and drivers must
128             set the array to zero.</entry>
129           </row>
130         </tbody>
131       </tgroup>
132     </table>
133   </refsect1>
135   <refsect1>
136     &return-value;
138     <variablelist>
139       <varlistentry>
140         <term><errorcode>EINVAL</errorcode></term>
141         <listitem>
142           <para>The &v4l2-subdev-frame-interval-enum;
143           <structfield>pad</structfield> references a non-existing pad, one of
144           the <structfield>code</structfield>, <structfield>width</structfield>
145           or <structfield>height</structfield> fields are invalid for the given
146           pad or the <structfield>index</structfield> field is out of bounds.
147           </para>
148         </listitem>
149       </varlistentry>
150     </variablelist>
151   </refsect1>
152 </refentry>