Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml

   1 <refentry id="vidioc-dbg-g-register">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_DBG_G_REGISTER</refname>
   9     <refname>VIDIOC_DBG_S_REGISTER</refname>
  10     <refpurpose>Read or write hardware registers</refpurpose>
  11   </refnamediv>
  12
  13   <refsynopsisdiv>
  14     <funcsynopsis>
  15       <funcprototype>
  16         <funcdef>int <function>ioctl</function></funcdef>
  17         <paramdef>int <parameter>fd</parameter></paramdef>
  18         <paramdef>int <parameter>request</parameter></paramdef>
  19         <paramdef>struct v4l2_dbg_register *<parameter>argp</parameter></paramdef>
  20       </funcprototype>
  21     </funcsynopsis>
  22     <funcsynopsis>
  23       <funcprototype>
  24         <funcdef>int <function>ioctl</function></funcdef>
  25         <paramdef>int <parameter>fd</parameter></paramdef>
  26         <paramdef>int <parameter>request</parameter></paramdef>
  27         <paramdef>const struct v4l2_dbg_register
  28 *<parameter>argp</parameter></paramdef>
  29       </funcprototype>
  30     </funcsynopsis>
  31   </refsynopsisdiv>
  32
  33   <refsect1>
  34     <title>Arguments</title>
  35
  36     <variablelist>
  37       <varlistentry>
  38         <term><parameter>fd</parameter></term>
  39         <listitem>
  40           <para>&fd;</para>
  41         </listitem>
  42       </varlistentry>
  43       <varlistentry>
  44         <term><parameter>request</parameter></term>
  45         <listitem>
  46           <para>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</para>
  47         </listitem>
  48       </varlistentry>
  49       <varlistentry>
  50         <term><parameter>argp</parameter></term>
  51         <listitem>
  52           <para></para>
  53         </listitem>
  54       </varlistentry>
  55     </variablelist>
  56   </refsect1>
  57
  58   <refsect1>
  59     <title>Description</title>
  60
  61     <note>
  62       <title>Experimental</title>
  63
  64       <para>This is an <link linkend="experimental">experimental</link>
  65 interface and may change in the future.</para>
  66     </note>
  67
  68     <para>For driver debugging purposes these ioctls allow test
  69 applications to access hardware registers directly. Regular
  70 applications must not use them.</para>
  71
  72     <para>Since writing or even reading registers can jeopardize the
  73 system security, its stability and damage the hardware, both ioctls
  74 require superuser privileges. Additionally the Linux kernel must be
  75 compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option
  76 to enable these ioctls.</para>
  77
  78     <para>To write a register applications must initialize all fields
  79 of a &v4l2-dbg-register; and call
  80 <constant>VIDIOC_DBG_S_REGISTER</constant> with a pointer to this
  81 structure. The <structfield>match.type</structfield> and
  82 <structfield>match.addr</structfield> or <structfield>match.name</structfield>
  83 fields select a chip on the TV
  84 card, the <structfield>reg</structfield> field specifies a register
  85 number and the <structfield>val</structfield> field the value to be
  86 written into the register.</para>
  87
  88     <para>To read a register applications must initialize the
  89 <structfield>match.type</structfield>,
  90 <structfield>match.chip</structfield> or <structfield>match.name</structfield> and
  91 <structfield>reg</structfield> fields, and call
  92 <constant>VIDIOC_DBG_G_REGISTER</constant> with a pointer to this
  93 structure. On success the driver stores the register value in the
  94 <structfield>val</structfield> field. On failure the structure remains
  95 unchanged.</para>
  96
  97     <para>When <structfield>match.type</structfield> is
  98 <constant>V4L2_CHIP_MATCH_HOST</constant>,
  99 <structfield>match.addr</structfield> selects the nth non-&i2c; chip
 100 on the TV card.  The number zero always selects the host chip, &eg; the
 101 chip connected to the PCI or USB bus. You can find out which chips are
 102 present with the &VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>
 103
 104     <para>When <structfield>match.type</structfield> is
 105 <constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant>,
 106 <structfield>match.name</structfield> contains the I2C driver name.
 107 For instance
 108 <constant>"saa7127"</constant> will match any chip
 109 supported by the saa7127 driver, regardless of its &i2c; bus address.
 110 When multiple chips supported by the same driver are present, the
 111 effect of these ioctls is undefined. Again with the
 112 &VIDIOC-DBG-G-CHIP-IDENT; ioctl you can find out which &i2c; chips are
 113 present.</para>
 114
 115     <para>When <structfield>match.type</structfield> is
 116 <constant>V4L2_CHIP_MATCH_I2C_ADDR</constant>,
 117 <structfield>match.addr</structfield> selects a chip by its 7 bit &i2c;
 118 bus address.</para>
 119
 120     <para>When <structfield>match.type</structfield> is
 121 <constant>V4L2_CHIP_MATCH_AC97</constant>,
 122 <structfield>match.addr</structfield> selects the nth AC97 chip
 123 on the TV card.</para>
 124
 125     <note>
 126       <title>Success not guaranteed</title>
 127
 128       <para>Due to a flaw in the Linux &i2c; bus driver these ioctls may
 129 return successfully without actually reading or writing a register. To
 130 catch the most likely failure we recommend a &VIDIOC-DBG-G-CHIP-IDENT;
 131 call confirming the presence of the selected &i2c; chip.</para>
 132     </note>
 133
 134     <para>These ioctls are optional, not all drivers may support them.
 135 However when a driver supports these ioctls it must also support
 136 &VIDIOC-DBG-G-CHIP-IDENT;. Conversely it may support
 137 <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> but not these ioctls.</para>
 138
 139     <para><constant>VIDIOC_DBG_G_REGISTER</constant> and
 140 <constant>VIDIOC_DBG_S_REGISTER</constant> were introduced in Linux
 141 2.6.21, but their API was changed to the one described here in kernel 2.6.29.</para>
 142
 143     <para>We recommended the <application>v4l2-dbg</application>
 144 utility over calling these ioctls directly. It is available from the
 145 LinuxTV v4l-dvb repository; see <ulink
 146 url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
 147 access instructions.</para>
 148
 149     <!-- Note for convenience vidioc-dbg-g-chip-ident.sgml
 150          contains a duplicate of this table. -->
 151     <table pgwide="1" frame="none" id="v4l2-dbg-match">
 152       <title>struct <structname>v4l2_dbg_match</structname></title>
 153       <tgroup cols="4">
 154         &cs-ustr;
 155         <tbody valign="top">
 156           <row>
 157             <entry>__u32</entry>
 158             <entry><structfield>type</structfield></entry>
 159             <entry>See <xref linkend="ident-chip-match-types" /> for a list of
 160 possible types.</entry>
 161           </row>
 162           <row>
 163             <entry>union</entry>
 164             <entry>(anonymous)</entry>
 165           </row>
 166           <row>
 167             <entry></entry>
 168             <entry>__u32</entry>
 169             <entry><structfield>addr</structfield></entry>
 170             <entry>Match a chip by this number, interpreted according
 171 to the <structfield>type</structfield> field.</entry>
 172           </row>
 173           <row>
 174             <entry></entry>
 175             <entry>char</entry>
 176             <entry><structfield>name[32]</structfield></entry>
 177             <entry>Match a chip by this name, interpreted according
 178 to the <structfield>type</structfield> field.</entry>
 179           </row>
 180         </tbody>
 181       </tgroup>
 182     </table>
 183
 184
 185     <table pgwide="1" frame="none" id="v4l2-dbg-register">
 186       <title>struct <structname>v4l2_dbg_register</structname></title>
 187       <tgroup cols="4">
 188         <colspec colname="c1" />
 189         <colspec colname="c2" />
 190         <colspec colname="c4" />
 191         <tbody valign="top">
 192           <row>
 193             <entry>struct v4l2_dbg_match</entry>
 194             <entry><structfield>match</structfield></entry>
 195             <entry>How to match the chip, see <xref linkend="v4l2-dbg-match" />.</entry>
 196           </row>
 197           <row>
 198             <entry>__u64</entry>
 199             <entry><structfield>reg</structfield></entry>
 200             <entry>A register number.</entry>
 201           </row>
 202           <row>
 203             <entry>__u64</entry>
 204             <entry><structfield>val</structfield></entry>
 205             <entry>The value read from, or to be written into the
 206 register.</entry>
 207           </row>
 208         </tbody>
 209       </tgroup>
 210     </table>
 211
 212     <!-- Note for convenience vidioc-dbg-g-chip-ident.sgml
 213          contains a duplicate of this table. -->
 214     <table pgwide="1" frame="none" id="chip-match-types">
 215       <title>Chip Match Types</title>
 216       <tgroup cols="3">
 217         &cs-def;
 218         <tbody valign="top">
 219           <row>
 220             <entry><constant>V4L2_CHIP_MATCH_HOST</constant></entry>
 221             <entry>0</entry>
 222             <entry>Match the nth chip on the card, zero for the
 223             host chip. Does not match &i2c; chips.</entry>
 224           </row>
 225           <row>
 226             <entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry>
 227             <entry>1</entry>
 228             <entry>Match an &i2c; chip by its driver name.</entry>
 229           </row>
 230           <row>
 231             <entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry>
 232             <entry>2</entry>
 233             <entry>Match a chip by its 7 bit &i2c; bus address.</entry>
 234           </row>
 235           <row>
 236             <entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry>
 237             <entry>3</entry>
 238             <entry>Match the nth anciliary AC97 chip.</entry>
 239           </row>
 240         </tbody>
 241       </tgroup>
 242     </table>
 243   </refsect1>
 244
 245   <refsect1>
 246     &return-value;
 247
 248     <variablelist>
 249       <varlistentry>
 250         <term><errorcode>EPERM</errorcode></term>
 251         <listitem>
 252           <para>Insufficient permissions. Root privileges are required
 253 to execute these ioctls.</para>
 254         </listitem>
 255       </varlistentry>
 256     </variablelist>
 257   </refsect1>
 258 </refentry>