Merge branch 'x86-cpu-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git...
[linux-2.6.git] / Documentation / DocBook / v4l / vidioc-dbg-g-chip-ident.xml
1 <refentry id="vidioc-dbg-g-chip-ident">
2   <refmeta>
3     <refentrytitle>ioctl VIDIOC_DBG_G_CHIP_IDENT</refentrytitle>
4     &manvol;
5   </refmeta>
6
7   <refnamediv>
8     <refname>VIDIOC_DBG_G_CHIP_IDENT</refname>
9     <refpurpose>Identify the chips on a TV card</refpurpose>
10   </refnamediv>
11
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_dbg_chip_ident
19 *<parameter>argp</parameter></paramdef>
20       </funcprototype>
21     </funcsynopsis>
22   </refsynopsisdiv>
23
24   <refsect1>
25     <title>Arguments</title>
26
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_DBG_G_CHIP_IDENT</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>
48
49   <refsect1>
50     <title>Description</title>
51
52     <note>
53       <title>Experimental</title>
54
55       <para>This is an <link
56 linkend="experimental">experimental</link> interface and may change in
57 the future.</para>
58     </note>
59
60     <para>For driver debugging purposes this ioctl allows test
61 applications to query the driver about the chips present on the TV
62 card. Regular applications must not use it. When you found a chip
63 specific bug, please contact the linux-media mailing list (&v4l-ml;)
64 so it can be fixed.</para>
65
66     <para>To query the driver applications must initialize the
67 <structfield>match.type</structfield> and
68 <structfield>match.addr</structfield> or <structfield>match.name</structfield>
69 fields of a &v4l2-dbg-chip-ident;
70 and call <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> with a pointer to
71 this structure. On success the driver stores information about the
72 selected chip in the <structfield>ident</structfield> and
73 <structfield>revision</structfield> fields. On failure the structure
74 remains unchanged.</para>
75
76     <para>When <structfield>match.type</structfield> is
77 <constant>V4L2_CHIP_MATCH_HOST</constant>,
78 <structfield>match.addr</structfield> selects the nth non-&i2c; chip
79 on the TV card. You can enumerate all chips by starting at zero and
80 incrementing <structfield>match.addr</structfield> by one until
81 <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;.
82 The number zero always selects the host chip, &eg; the chip connected
83 to the PCI or USB bus.</para>
84
85     <para>When <structfield>match.type</structfield> is
86 <constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant>,
87 <structfield>match.name</structfield> contains the I2C driver name.
88 For instance
89 <constant>"saa7127"</constant> will match any chip
90 supported by the saa7127 driver, regardless of its &i2c; bus address.
91 When multiple chips supported by the same driver are present, the
92 ioctl will return <constant>V4L2_IDENT_AMBIGUOUS</constant> in the
93 <structfield>ident</structfield> field.</para>
94
95     <para>When <structfield>match.type</structfield> is
96 <constant>V4L2_CHIP_MATCH_I2C_ADDR</constant>,
97 <structfield>match.addr</structfield> selects a chip by its 7 bit
98 &i2c; bus address.</para>
99
100     <para>When <structfield>match.type</structfield> is
101 <constant>V4L2_CHIP_MATCH_AC97</constant>,
102 <structfield>match.addr</structfield> selects the nth AC97 chip
103 on the TV card. You can enumerate all chips by starting at zero and
104 incrementing <structfield>match.addr</structfield> by one until
105 <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;.</para>
106
107     <para>On success, the <structfield>ident</structfield> field will
108 contain a chip ID from the Linux
109 <filename>media/v4l2-chip-ident.h</filename> header file, and the
110 <structfield>revision</structfield> field will contain a driver
111 specific value, or zero if no particular revision is associated with
112 this chip.</para>
113
114     <para>When the driver could not identify the selected chip,
115 <structfield>ident</structfield> will contain
116 <constant>V4L2_IDENT_UNKNOWN</constant>. When no chip matched
117 the ioctl will succeed but the
118 <structfield>ident</structfield> field will contain
119 <constant>V4L2_IDENT_NONE</constant>. If multiple chips matched,
120 <structfield>ident</structfield> will contain
121 <constant>V4L2_IDENT_AMBIGUOUS</constant>. In all these cases the
122 <structfield>revision</structfield> field remains unchanged.</para>
123
124     <para>This ioctl is optional, not all drivers may support it. It
125 was introduced in Linux 2.6.21, but the API was changed to the
126 one described here in 2.6.29.</para>
127
128     <para>We recommended the <application>v4l2-dbg</application>
129 utility over calling this ioctl directly. It is available from the
130 LinuxTV v4l-dvb repository; see <ulink
131 url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
132 access instructions.</para>
133
134     <!-- Note for convenience vidioc-dbg-g-register.sgml
135          contains a duplicate of this table. -->
136     <table pgwide="1" frame="none" id="ident-v4l2-dbg-match">
137       <title>struct <structname>v4l2_dbg_match</structname></title>
138       <tgroup cols="4">
139         &cs-ustr;
140         <tbody valign="top">
141           <row>
142             <entry>__u32</entry>
143             <entry><structfield>type</structfield></entry>
144             <entry>See <xref linkend="ident-chip-match-types" /> for a list of
145 possible types.</entry>
146           </row>
147           <row>
148             <entry>union</entry>
149             <entry>(anonymous)</entry>
150           </row>
151           <row>
152             <entry></entry>
153             <entry>__u32</entry>
154             <entry><structfield>addr</structfield></entry>
155             <entry>Match a chip by this number, interpreted according
156 to the <structfield>type</structfield> field.</entry>
157           </row>
158           <row>
159             <entry></entry>
160             <entry>char</entry>
161             <entry><structfield>name[32]</structfield></entry>
162             <entry>Match a chip by this name, interpreted according
163 to the <structfield>type</structfield> field.</entry>
164           </row>
165         </tbody>
166       </tgroup>
167     </table>
168
169     <table pgwide="1" frame="none" id="v4l2-dbg-chip-ident">
170       <title>struct <structname>v4l2_dbg_chip_ident</structname></title>
171       <tgroup cols="3">
172         &cs-str;
173         <tbody valign="top">
174           <row>
175             <entry>struct v4l2_dbg_match</entry>
176             <entry><structfield>match</structfield></entry>
177             <entry>How to match the chip, see <xref linkend="ident-v4l2-dbg-match" />.</entry>
178           </row>
179           <row>
180             <entry>__u32</entry>
181             <entry><structfield>ident</structfield></entry>
182             <entry>A chip identifier as defined in the Linux
183 <filename>media/v4l2-chip-ident.h</filename> header file, or one of
184 the values from <xref linkend="chip-ids" />.</entry>
185           </row>
186           <row>
187             <entry>__u32</entry>
188             <entry><structfield>revision</structfield></entry>
189             <entry>A chip revision, chip and driver specific.</entry>
190           </row>
191         </tbody>
192       </tgroup>
193     </table>
194
195     <!-- Note for convenience vidioc-dbg-g-register.sgml
196          contains a duplicate of this table. -->
197     <table pgwide="1" frame="none" id="ident-chip-match-types">
198       <title>Chip Match Types</title>
199       <tgroup cols="3">
200         &cs-def;
201         <tbody valign="top">
202           <row>
203             <entry><constant>V4L2_CHIP_MATCH_HOST</constant></entry>
204             <entry>0</entry>
205             <entry>Match the nth chip on the card, zero for the
206             host chip. Does not match &i2c; chips.</entry>
207           </row>
208           <row>
209             <entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry>
210             <entry>1</entry>
211             <entry>Match an &i2c; chip by its driver name.</entry>
212           </row>
213           <row>
214             <entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry>
215             <entry>2</entry>
216             <entry>Match a chip by its 7 bit &i2c; bus address.</entry>
217           </row>
218           <row>
219             <entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry>
220             <entry>3</entry>
221             <entry>Match the nth anciliary AC97 chip.</entry>
222           </row>
223         </tbody>
224       </tgroup>
225     </table>
226
227     <!-- This is an anonymous enum in media/v4l2-chip-ident.h. -->
228     <table pgwide="1" frame="none" id="chip-ids">
229       <title>Chip Identifiers</title>
230       <tgroup cols="3">
231         &cs-def;
232         <tbody valign="top">
233           <row>
234             <entry><constant>V4L2_IDENT_NONE</constant></entry>
235             <entry>0</entry>
236             <entry>No chip matched.</entry>
237           </row>
238           <row>
239             <entry><constant>V4L2_IDENT_AMBIGUOUS</constant></entry>
240             <entry>1</entry>
241             <entry>Multiple chips matched.</entry>
242           </row>
243           <row>
244             <entry><constant>V4L2_IDENT_UNKNOWN</constant></entry>
245             <entry>2</entry>
246             <entry>A chip is present at this address, but the driver
247 could not identify it.</entry>
248           </row>
249         </tbody>
250       </tgroup>
251     </table>
252   </refsect1>
253
254   <refsect1>
255     &return-value;
256
257     <variablelist>
258       <varlistentry>
259         <term><errorcode>EINVAL</errorcode></term>
260         <listitem>
261           <para>The driver does not support this ioctl, or the
262 <structfield>match_type</structfield> is invalid.</para>
263         </listitem>
264       </varlistentry>
265      </variablelist>
266   </refsect1>
267 </refentry>
268
269 <!--
270 Local Variables:
271 mode: sgml
272 sgml-parent-document: "v4l2.sgml"
273 indent-tabs-mode: nil
274 End:
275 -->