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.16. Page generated on 2014-08-06 21:39 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, &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-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="http://linuxtv.org/repo/">http://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>
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.