Based on kernel version 3.10. Page generated on 2013-07-08 20:09 EST.
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, ⪚ 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_BRIDGE</constant></entry> 204 <entry>0</entry> 205 <entry>Match the nth chip on the card, zero for the 206 bridge chip. Does not match sub-devices.</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 <row> 224 <entry><constant>V4L2_CHIP_MATCH_SUBDEV</constant></entry> 225 <entry>4</entry> 226 <entry>Match the nth sub-device. Can't be used with this ioctl.</entry> 227 </row> 228 </tbody> 229 </tgroup> 230 </table> 231 232 <!-- This is an anonymous enum in media/v4l2-chip-ident.h. --> 233 <table pgwide="1" frame="none" id="chip-ids"> 234 <title>Chip Identifiers</title> 235 <tgroup cols="3"> 236 &cs-def; 237 <tbody valign="top"> 238 <row> 239 <entry><constant>V4L2_IDENT_NONE</constant></entry> 240 <entry>0</entry> 241 <entry>No chip matched.</entry> 242 </row> 243 <row> 244 <entry><constant>V4L2_IDENT_AMBIGUOUS</constant></entry> 245 <entry>1</entry> 246 <entry>Multiple chips matched.</entry> 247 </row> 248 <row> 249 <entry><constant>V4L2_IDENT_UNKNOWN</constant></entry> 250 <entry>2</entry> 251 <entry>A chip is present at this address, but the driver 252 could not identify it.</entry> 253 </row> 254 </tbody> 255 </tgroup> 256 </table> 257 </refsect1> 258 259 <refsect1> 260 &return-value; 261 262 <variablelist> 263 <varlistentry> 264 <term><errorcode>EINVAL</errorcode></term> 265 <listitem> 266 <para>The <structfield>match_type</structfield> is invalid.</para> 267 </listitem> 268 </varlistentry> 269 </variablelist> 270 </refsect1> 271 </refentry>
