1 <refentry id="vidioc-dbg-g-chip-ident">
3 <refentrytitle>ioctl VIDIOC_DBG_G_CHIP_IDENT</refentrytitle>
8 <refname>VIDIOC_DBG_G_CHIP_IDENT</refname>
9 <refpurpose>Identify the chips on a TV card</refpurpose>
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>
25 <title>Arguments</title>
29 <term><parameter>fd</parameter></term>
35 <term><parameter>request</parameter></term>
37 <para>VIDIOC_DBG_G_CHIP_IDENT</para>
41 <term><parameter>argp</parameter></term>
50 <title>Description</title>
53 <title>Experimental</title>
55 <para>This is an <link
56 linkend="experimental">experimental</link> interface and may change in
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>
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>
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, ⪚ the chip connected
83 to the PCI or USB bus.</para>
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.
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>
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>
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>
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
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>
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>
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>
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>
143 <entry><structfield>type</structfield></entry>
144 <entry>See <xref linkend="ident-chip-match-types" /> for a list of
145 possible types.</entry>
149 <entry>(anonymous)</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>
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>
169 <table pgwide="1" frame="none" id="v4l2-dbg-chip-ident">
170 <title>struct <structname>v4l2_dbg_chip_ident</structname></title>
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>
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>
188 <entry><structfield>revision</structfield></entry>
189 <entry>A chip revision, chip and driver specific.</entry>
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>
203 <entry><constant>V4L2_CHIP_MATCH_HOST</constant></entry>
205 <entry>Match the nth chip on the card, zero for the
206 host chip. Does not match &i2c; chips.</entry>
209 <entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry>
211 <entry>Match an &i2c; chip by its driver name.</entry>
214 <entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry>
216 <entry>Match a chip by its 7 bit &i2c; bus address.</entry>
219 <entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry>
221 <entry>Match the nth anciliary AC97 chip.</entry>
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>
234 <entry><constant>V4L2_IDENT_NONE</constant></entry>
236 <entry>No chip matched.</entry>
239 <entry><constant>V4L2_IDENT_AMBIGUOUS</constant></entry>
241 <entry>Multiple chips matched.</entry>
244 <entry><constant>V4L2_IDENT_UNKNOWN</constant></entry>
246 <entry>A chip is present at this address, but the driver
247 could not identify it.</entry>
259 <term><errorcode>EINVAL</errorcode></term>
261 <para>The driver does not support this ioctl, or the
262 <structfield>match_type</structfield> is invalid.</para>
272 sgml-parent-document: "v4l2.sgml"
273 indent-tabs-mode: nil