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; except for <structfield>size</structfield> 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.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
93structure. On success the driver stores the register value in the
94<structfield>val</structfield> field and the size (in bytes) of the
95value 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
100on the TV card.  The number zero always selects the host chip, &eg; the
101chip connected to the PCI or USB bus. You can find out which chips are
102present 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.
109However 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
1152.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>
118utility over calling these ioctls directly. It is available from the
119LinuxTV v4l-dvb repository; see <ulink
120url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
121access 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
134possible 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
145to 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
152to 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
185register.</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
222to execute these ioctls.</para>
223	</listitem>
224      </varlistentry>
225    </variablelist>
226  </refsect1>
227</refentry>
228