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 56linkend="experimental">experimental</link> interface and may change in 57the future.</para> 58 </note> 59 60 <para>For driver debugging purposes this ioctl allows test 61applications to query the driver about the chips present on the TV 62card. Regular applications must not use it. When you found a chip 63specific bug, please contact the linux-media mailing list (&v4l-ml;) 64so 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> 69fields of a &v4l2-dbg-chip-ident; 70and call <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> with a pointer to 71this structure. On success the driver stores information about the 72selected chip in the <structfield>ident</structfield> and 73<structfield>revision</structfield> fields. On failure the structure 74remains 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 79on the TV card. You can enumerate all chips by starting at zero and 80incrementing <structfield>match.addr</structfield> by one until 81<constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;. 82The number zero always selects the host chip, ⪚ the chip connected 83to 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. 88For instance 89<constant>"saa7127"</constant> will match any chip 90supported by the saa7127 driver, regardless of its &i2c; bus address. 91When multiple chips supported by the same driver are present, the 92ioctl 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 103on the TV card. You can enumerate all chips by starting at zero and 104incrementing <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 108contain 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 111specific value, or zero if no particular revision is associated with 112this 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 117the 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 125was introduced in Linux 2.6.21, but the API was changed to the 126one described here in 2.6.29.</para> 127 128 <para>We recommended the <application>v4l2-dbg</application> 129utility over calling this ioctl directly. It is available from the 130LinuxTV v4l-dvb repository; see <ulink 131url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for 132access 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 145possible 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 156to 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 163to 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 184the 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 247could 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<!-- 270Local Variables: 271mode: sgml 272sgml-parent-document: "v4l2.sgml" 273indent-tabs-mode: nil 274End: 275--> 276