About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 23:04 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; 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>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog
Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.