Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml

   1 <refentry id="vidioc-dbg-g-chip-info">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_DBG_G_CHIP_INFO</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_DBG_G_CHIP_INFO</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_info
  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_INFO</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>Additionally the Linux kernel must be compiled with the
  67 <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option to enable this ioctl.</para>
  68
  69     <para>To query the driver applications must initialize the
  70 <structfield>match.type</structfield> and
  71 <structfield>match.addr</structfield> or <structfield>match.name</structfield>
  72 fields of a &v4l2-dbg-chip-info;
  73 and call <constant>VIDIOC_DBG_G_CHIP_INFO</constant> with a pointer to
  74 this structure. On success the driver stores information about the
  75 selected chip in the <structfield>name</structfield> and
  76 <structfield>flags</structfield> fields. On failure the structure
  77 remains unchanged.</para>
  78
  79     <para>When <structfield>match.type</structfield> is
  80 <constant>V4L2_CHIP_MATCH_BRIDGE</constant>,
  81 <structfield>match.addr</structfield> selects the nth bridge 'chip'
  82 on the TV card. You can enumerate all chips by starting at zero and
  83 incrementing <structfield>match.addr</structfield> by one until
  84 <constant>VIDIOC_DBG_G_CHIP_INFO</constant> fails with an &EINVAL;.
  85 The number zero always selects the bridge chip itself, &eg; the chip
  86 connected to the PCI or USB bus. Non-zero numbers identify specific
  87 parts of the bridge chip such as an AC97 register block.</para>
  88
  89     <para>When <structfield>match.type</structfield> is
  90 <constant>V4L2_CHIP_MATCH_SUBDEV</constant>,
  91 <structfield>match.addr</structfield> selects the nth sub-device. This
  92 allows you to enumerate over all sub-devices.</para>
  93
  94     <para>On success, the <structfield>name</structfield> field will
  95 contain a chip name and the <structfield>flags</structfield> field will
  96 contain <constant>V4L2_CHIP_FL_READABLE</constant> if the driver supports
  97 reading registers from the device or <constant>V4L2_CHIP_FL_WRITABLE</constant>
  98 if the driver supports writing registers to the device.</para>
  99
 100     <para>We recommended the <application>v4l2-dbg</application>
 101 utility over calling this ioctl directly. It is available from the
 102 LinuxTV v4l-dvb repository; see <ulink
 103 url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
 104 access instructions.</para>
 105
 106     <!-- Note for convenience vidioc-dbg-g-register.sgml
 107          contains a duplicate of this table. -->
 108     <table pgwide="1" frame="none" id="name-v4l2-dbg-match">
 109       <title>struct <structname>v4l2_dbg_match</structname></title>
 110       <tgroup cols="4">
 111         &cs-ustr;
 112         <tbody valign="top">
 113           <row>
 114             <entry>__u32</entry>
 115             <entry><structfield>type</structfield></entry>
 116             <entry>See <xref linkend="name-chip-match-types" /> for a list of
 117 possible types.</entry>
 118           </row>
 119           <row>
 120             <entry>union</entry>
 121             <entry>(anonymous)</entry>
 122           </row>
 123           <row>
 124             <entry></entry>
 125             <entry>__u32</entry>
 126             <entry><structfield>addr</structfield></entry>
 127             <entry>Match a chip by this number, interpreted according
 128 to the <structfield>type</structfield> field.</entry>
 129           </row>
 130           <row>
 131             <entry></entry>
 132             <entry>char</entry>
 133             <entry><structfield>name[32]</structfield></entry>
 134             <entry>Match a chip by this name, interpreted according
 135 to the <structfield>type</structfield> field.</entry>
 136           </row>
 137         </tbody>
 138       </tgroup>
 139     </table>
 140
 141     <table pgwide="1" frame="none" id="v4l2-dbg-chip-info">
 142       <title>struct <structname>v4l2_dbg_chip_info</structname></title>
 143       <tgroup cols="3">
 144         &cs-str;
 145         <tbody valign="top">
 146           <row>
 147             <entry>struct v4l2_dbg_match</entry>
 148             <entry><structfield>match</structfield></entry>
 149             <entry>How to match the chip, see <xref linkend="name-v4l2-dbg-match" />.</entry>
 150           </row>
 151           <row>
 152             <entry>char</entry>
 153             <entry><structfield>name[32]</structfield></entry>
 154             <entry>The name of the chip.</entry>
 155           </row>
 156           <row>
 157             <entry>__u32</entry>
 158             <entry><structfield>flags</structfield></entry>
 159             <entry>Set by the driver. If <constant>V4L2_CHIP_FL_READABLE</constant>
 160 is set, then the driver supports reading registers from the device. If
 161 <constant>V4L2_CHIP_FL_WRITABLE</constant> is set, then it supports writing registers.</entry>
 162           </row>
 163           <row>
 164             <entry>__u32</entry>
 165             <entry><structfield>reserved[8]</structfield></entry>
 166             <entry>Reserved fields, both application and driver must set these to 0.</entry>
 167           </row>
 168         </tbody>
 169       </tgroup>
 170     </table>
 171
 172     <!-- Note for convenience vidioc-dbg-g-register.sgml
 173          contains a duplicate of this table. -->
 174     <table pgwide="1" frame="none" id="name-chip-match-types">
 175       <title>Chip Match Types</title>
 176       <tgroup cols="3">
 177         &cs-def;
 178         <tbody valign="top">
 179           <row>
 180             <entry><constant>V4L2_CHIP_MATCH_BRIDGE</constant></entry>
 181             <entry>0</entry>
 182             <entry>Match the nth chip on the card, zero for the
 183             bridge chip. Does not match sub-devices.</entry>
 184           </row>
 185           <row>
 186             <entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry>
 187             <entry>1</entry>
 188             <entry>Match an &i2c; chip by its driver name. Can't be used with this ioctl.</entry>
 189           </row>
 190           <row>
 191             <entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry>
 192             <entry>2</entry>
 193             <entry>Match a chip by its 7 bit &i2c; bus address. Can't be used with this ioctl.</entry>
 194           </row>
 195           <row>
 196             <entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry>
 197             <entry>3</entry>
 198             <entry>Match the nth anciliary AC97 chip. Can't be used with this ioctl.</entry>
 199           </row>
 200           <row>
 201             <entry><constant>V4L2_CHIP_MATCH_SUBDEV</constant></entry>
 202             <entry>4</entry>
 203             <entry>Match the nth sub-device.</entry>
 204           </row>
 205         </tbody>
 206       </tgroup>
 207     </table>
 208   </refsect1>
 209
 210   <refsect1>
 211     &return-value;
 212
 213     <variablelist>
 214       <varlistentry>
 215         <term><errorcode>EINVAL</errorcode></term>
 216         <listitem>
 217           <para>The <structfield>match_type</structfield> is invalid or
 218 no device could be matched.</para>
 219         </listitem>
 220       </varlistentry>
 221      </variablelist>
 222   </refsect1>
 223 </refentry>