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> 65interface and may change in the future.</para> 66 </note> 67 68 <para>For driver debugging purposes these ioctls allow test 69applications to access hardware registers directly. Regular 70applications must not use them.</para> 71 72 <para>Since writing or even reading registers can jeopardize the 73system security, its stability and damage the hardware, both ioctls 74require superuser privileges. Additionally the Linux kernel must be 75compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option 76to enable these ioctls.</para> 77 78 <para>To write a register applications must initialize all fields 79of a &v4l2-dbg-register; and call 80<constant>VIDIOC_DBG_S_REGISTER</constant> with a pointer to this 81structure. The <structfield>match.type</structfield> and 82<structfield>match.addr</structfield> or <structfield>match.name</structfield> 83fields select a chip on the TV 84card, the <structfield>reg</structfield> field specifies a register 85number and the <structfield>val</structfield> field the value to be 86written 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 93structure. On success the driver stores the register value in the 94<structfield>val</structfield> field. On failure the structure remains 95unchanged.</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 100on the TV card. The number zero always selects the host chip, ⪚ the 101chip connected to the PCI or USB bus. You can find out which chips are 102present 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. 107For instance 108<constant>"saa7127"</constant> will match any chip 109supported by the saa7127 driver, regardless of its &i2c; bus address. 110When multiple chips supported by the same driver are present, the 111effect of these ioctls is undefined. Again with the 112&VIDIOC-DBG-G-CHIP-IDENT; ioctl you can find out which &i2c; chips are 113present.</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; 118bus 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 123on 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 129return successfully without actually reading or writing a register. To 130catch the most likely failure we recommend a &VIDIOC-DBG-G-CHIP-IDENT; 131call confirming the presence of the selected &i2c; chip.</para> 132 </note> 133 134 <para>These ioctls are optional, not all drivers may support them. 135However 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 1412.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> 144utility over calling these ioctls directly. It is available from the 145LinuxTV v4l-dvb repository; see <ulink 146url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for 147access 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 160possible 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 171to 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 178to 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 206register.</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>EINVAL</errorcode></term> 251 <listitem> 252 <para>The driver does not support this ioctl, or the kernel 253was not compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> 254option, or the <structfield>match_type</structfield> is invalid, or the 255selected chip or register does not exist.</para> 256 </listitem> 257 </varlistentry> 258 <varlistentry> 259 <term><errorcode>EPERM</errorcode></term> 260 <listitem> 261 <para>Insufficient permissions. Root privileges are required 262to execute these ioctls.</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