1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
<refentry id="vidioc-dbg-g-register">
<refmeta>
<refentrytitle>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_DBG_G_REGISTER</refname>
<refname>VIDIOC_DBG_S_REGISTER</refname>
<refpurpose>Read or write hardware registers</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct v4l2_dbg_register *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>const struct v4l2_dbg_register
*<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<note>
<title>Experimental</title>
<para>This is an <link linkend="experimental">experimental</link>
interface and may change in the future.</para>
</note>
<para>For driver debugging purposes these ioctls allow test
applications to access hardware registers directly. Regular
applications must not use them.</para>
<para>Since writing or even reading registers can jeopardize the
system security, its stability and damage the hardware, both ioctls
require superuser privileges. Additionally the Linux kernel must be
compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option
to enable these ioctls.</para>
<para>To write a register applications must initialize all fields
of a &v4l2-dbg-register; except for <structfield>size</structfield> and call
<constant>VIDIOC_DBG_S_REGISTER</constant> with a pointer to this
structure. The <structfield>match.type</structfield> and
<structfield>match.addr</structfield> or <structfield>match.name</structfield>
fields select a chip on the TV
card, the <structfield>reg</structfield> field specifies a register
number and the <structfield>val</structfield> field the value to be
written into the register.</para>
<para>To read a register applications must initialize the
<structfield>match.type</structfield>,
<structfield>match.addr</structfield> or <structfield>match.name</structfield> and
<structfield>reg</structfield> fields, and call
<constant>VIDIOC_DBG_G_REGISTER</constant> with a pointer to this
structure. On success the driver stores the register value in the
<structfield>val</structfield> field and the size (in bytes) of the
value in <structfield>size</structfield>.</para>
<para>When <structfield>match.type</structfield> is
<constant>V4L2_CHIP_MATCH_BRIDGE</constant>,
<structfield>match.addr</structfield> selects the nth non-sub-device chip
on the TV card. The number zero always selects the host chip, ⪚ the
chip connected to the PCI or USB bus. You can find out which chips are
present with the &VIDIOC-DBG-G-CHIP-INFO; ioctl.</para>
<para>When <structfield>match.type</structfield> is
<constant>V4L2_CHIP_MATCH_SUBDEV</constant>,
<structfield>match.addr</structfield> selects the nth sub-device.</para>
<para>These ioctls are optional, not all drivers may support them.
However when a driver supports these ioctls it must also support
&VIDIOC-DBG-G-CHIP-INFO;. Conversely it may support
<constant>VIDIOC_DBG_G_CHIP_INFO</constant> but not these ioctls.</para>
<para><constant>VIDIOC_DBG_G_REGISTER</constant> and
<constant>VIDIOC_DBG_S_REGISTER</constant> were introduced in Linux
2.6.21, but their API was changed to the one described here in kernel 2.6.29.</para>
<para>We recommended the <application>v4l2-dbg</application>
utility over calling these ioctls directly. It is available from the
LinuxTV v4l-dvb repository; see <ulink
url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
access instructions.</para>
<!-- Note for convenience vidioc-dbg-g-chip-info.sgml
contains a duplicate of this table. -->
<table pgwide="1" frame="none" id="v4l2-dbg-match">
<title>struct <structname>v4l2_dbg_match</structname></title>
<tgroup cols="4">
&cs-ustr;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>type</structfield></entry>
<entry>See <xref linkend="chip-match-types" /> for a list of
possible types.</entry>
</row>
<row>
<entry>union</entry>
<entry>(anonymous)</entry>
</row>
<row>
<entry></entry>
<entry>__u32</entry>
<entry><structfield>addr</structfield></entry>
<entry>Match a chip by this number, interpreted according
to the <structfield>type</structfield> field.</entry>
</row>
<row>
<entry></entry>
<entry>char</entry>
<entry><structfield>name[32]</structfield></entry>
<entry>Match a chip by this name, interpreted according
to the <structfield>type</structfield> field. Currently unused.</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="v4l2-dbg-register">
<title>struct <structname>v4l2_dbg_register</structname></title>
<tgroup cols="4">
<colspec colname="c1" />
<colspec colname="c2" />
<colspec colname="c4" />
<tbody valign="top">
<row>
<entry>struct v4l2_dbg_match</entry>
<entry><structfield>match</structfield></entry>
<entry>How to match the chip, see <xref linkend="v4l2-dbg-match" />.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>size</structfield></entry>
<entry>The register size in bytes.</entry>
</row>
<row>
<entry>__u64</entry>
<entry><structfield>reg</structfield></entry>
<entry>A register number.</entry>
</row>
<row>
<entry>__u64</entry>
<entry><structfield>val</structfield></entry>
<entry>The value read from, or to be written into the
register.</entry>
</row>
</tbody>
</tgroup>
</table>
<!-- Note for convenience vidioc-dbg-g-chip-info.sgml
contains a duplicate of this table. -->
<table pgwide="1" frame="none" id="chip-match-types">
<title>Chip Match Types</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_CHIP_MATCH_BRIDGE</constant></entry>
<entry>0</entry>
<entry>Match the nth chip on the card, zero for the
bridge chip. Does not match sub-devices.</entry>
</row>
<row>
<entry><constant>V4L2_CHIP_MATCH_SUBDEV</constant></entry>
<entry>4</entry>
<entry>Match the nth sub-device.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
<variablelist>
<varlistentry>
<term><errorcode>EPERM</errorcode></term>
<listitem>
<para>Insufficient permissions. Root privileges are required
to execute these ioctls.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
|
