ARM: 7409/1: Do not call flush_cache_user_range with mmap_sem held
[linux/fpc-iii.git] / Documentation / DocBook / v4l / vidioc-dbg-g-register.xml
blob980c7f3e2fd6779c22d7d539de0b2a7abc251dec
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>
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>
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>
33   <refsect1>
34     <title>Arguments</title>
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>
58   <refsect1>
59     <title>Description</title>
61     <note>
62       <title>Experimental</title>
64       <para>This is an <link linkend="experimental">experimental</link>
65 interface and may change in the future.</para>
66     </note>
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>
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>
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>
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>
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>
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>
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>
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>
125     <note>
126       <title>Success not guaranteed</title>
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>
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>
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>
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>
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>
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>
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>
245   <refsect1>
246     &return-value;
248     <variablelist>
249       <varlistentry>
250         <term><errorcode>EINVAL</errorcode></term>
251         <listitem>
252           <para>The driver does not support this ioctl, or the kernel
253 was not compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant>
254 option, or the <structfield>match_type</structfield> is invalid, or the
255 selected 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
262 to execute these ioctls.</para>
263         </listitem>
264       </varlistentry>
265     </variablelist>
266   </refsect1>
267 </refentry>
269 <!--
270 Local Variables:
271 mode: sgml
272 sgml-parent-document: "v4l2.sgml"
273 indent-tabs-mode: nil
274 End: