Documentation/DocBook/media/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 <structfield>match_type</structfield> is invalid.</para>
 262         </listitem>
 263       </varlistentry>
 264      </variablelist>
 265   </refsect1>
 266 </refentry>