Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.
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; except for <structfield>size</structfield> 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.addr</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 and the size (in bytes) of the 95 value in <structfield>size</structfield>.</para> 96 97 <para>When <structfield>match.type</structfield> is 98 <constant>V4L2_CHIP_MATCH_BRIDGE</constant>, 99 <structfield>match.addr</structfield> selects the nth non-sub-device chip 100 on the TV card. The number zero always selects the host chip, ⪚ 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-INFO; ioctl.</para> 103 104 <para>When <structfield>match.type</structfield> is 105 <constant>V4L2_CHIP_MATCH_SUBDEV</constant>, 106 <structfield>match.addr</structfield> selects the nth sub-device.</para> 107 108 <para>These ioctls are optional, not all drivers may support them. 109 However when a driver supports these ioctls it must also support 110 &VIDIOC-DBG-G-CHIP-INFO;. Conversely it may support 111 <constant>VIDIOC_DBG_G_CHIP_INFO</constant> but not these ioctls.</para> 112 113 <para><constant>VIDIOC_DBG_G_REGISTER</constant> and 114 <constant>VIDIOC_DBG_S_REGISTER</constant> were introduced in Linux 115 2.6.21, but their API was changed to the one described here in kernel 2.6.29.</para> 116 117 <para>We recommended the <application>v4l2-dbg</application> 118 utility over calling these ioctls directly. It is available from the 119 LinuxTV v4l-dvb repository; see <ulink 120 url="https://linuxtv.org/repo/">https://linuxtv.org/repo/</ulink> for 121 access instructions.</para> 122 123 <!-- Note for convenience vidioc-dbg-g-chip-info.sgml 124 contains a duplicate of this table. --> 125 <table pgwide="1" frame="none" id="v4l2-dbg-match"> 126 <title>struct <structname>v4l2_dbg_match</structname></title> 127 <tgroup cols="4"> 128 &cs-ustr; 129 <tbody valign="top"> 130 <row> 131 <entry>__u32</entry> 132 <entry><structfield>type</structfield></entry> 133 <entry>See <xref linkend="chip-match-types" /> for a list of 134 possible types.</entry> 135 </row> 136 <row> 137 <entry>union</entry> 138 <entry>(anonymous)</entry> 139 </row> 140 <row> 141 <entry></entry> 142 <entry>__u32</entry> 143 <entry><structfield>addr</structfield></entry> 144 <entry>Match a chip by this number, interpreted according 145 to the <structfield>type</structfield> field.</entry> 146 </row> 147 <row> 148 <entry></entry> 149 <entry>char</entry> 150 <entry><structfield>name[32]</structfield></entry> 151 <entry>Match a chip by this name, interpreted according 152 to the <structfield>type</structfield> field. Currently unused.</entry> 153 </row> 154 </tbody> 155 </tgroup> 156 </table> 157 158 159 <table pgwide="1" frame="none" id="v4l2-dbg-register"> 160 <title>struct <structname>v4l2_dbg_register</structname></title> 161 <tgroup cols="4"> 162 <colspec colname="c1" /> 163 <colspec colname="c2" /> 164 <colspec colname="c4" /> 165 <tbody valign="top"> 166 <row> 167 <entry>struct v4l2_dbg_match</entry> 168 <entry><structfield>match</structfield></entry> 169 <entry>How to match the chip, see <xref linkend="v4l2-dbg-match" />.</entry> 170 </row> 171 <row> 172 <entry>__u32</entry> 173 <entry><structfield>size</structfield></entry> 174 <entry>The register size in bytes.</entry> 175 </row> 176 <row> 177 <entry>__u64</entry> 178 <entry><structfield>reg</structfield></entry> 179 <entry>A register number.</entry> 180 </row> 181 <row> 182 <entry>__u64</entry> 183 <entry><structfield>val</structfield></entry> 184 <entry>The value read from, or to be written into the 185 register.</entry> 186 </row> 187 </tbody> 188 </tgroup> 189 </table> 190 191 <!-- Note for convenience vidioc-dbg-g-chip-info.sgml 192 contains a duplicate of this table. --> 193 <table pgwide="1" frame="none" id="chip-match-types"> 194 <title>Chip Match Types</title> 195 <tgroup cols="3"> 196 &cs-def; 197 <tbody valign="top"> 198 <row> 199 <entry><constant>V4L2_CHIP_MATCH_BRIDGE</constant></entry> 200 <entry>0</entry> 201 <entry>Match the nth chip on the card, zero for the 202 bridge chip. Does not match sub-devices.</entry> 203 </row> 204 <row> 205 <entry><constant>V4L2_CHIP_MATCH_SUBDEV</constant></entry> 206 <entry>4</entry> 207 <entry>Match the nth sub-device.</entry> 208 </row> 209 </tbody> 210 </tgroup> 211 </table> 212 </refsect1> 213 214 <refsect1> 215 &return-value; 216 217 <variablelist> 218 <varlistentry> 219 <term><errorcode>EPERM</errorcode></term> 220 <listitem> 221 <para>Insufficient permissions. Root privileges are required 222 to execute these ioctls.</para> 223 </listitem> 224 </varlistentry> 225 </variablelist> 226 </refsect1> 227 </refentry>
