Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_DBG_G_REGISTER: |
5377d91f MH |
4 | |
5 | ************************************************** | |
6 | ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER | |
7 | ************************************************** | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
b7e67f6c | 18 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_dbg_register *argp ) |
5377d91f | 19 | |
b7e67f6c | 20 | .. cpp:function:: int ioctl( int fd, int request, const struct v4l2_dbg_register *argp ) |
5377d91f | 21 | |
586027ce | 22 | |
15e7d615 | 23 | Arguments |
5377d91f MH |
24 | ========= |
25 | ||
26 | ``fd`` | |
27 | File descriptor returned by :ref:`open() <func-open>`. | |
28 | ||
29 | ``request`` | |
30 | VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER | |
31 | ||
32 | ``argp`` | |
33 | ||
34 | ||
15e7d615 | 35 | Description |
5377d91f MH |
36 | =========== |
37 | ||
38 | **Note** | |
39 | ||
7347081e | 40 | This is an :ref:`experimental` interface and may |
5377d91f MH |
41 | change in the future. |
42 | ||
43 | For driver debugging purposes these ioctls allow test applications to | |
44 | access hardware registers directly. Regular applications must not use | |
45 | them. | |
46 | ||
47 | Since writing or even reading registers can jeopardize the system | |
48 | security, its stability and damage the hardware, both ioctls require | |
49 | superuser privileges. Additionally the Linux kernel must be compiled | |
50 | with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls. | |
51 | ||
52 | To write a register applications must initialize all fields of a struct | |
53 | :ref:`v4l2_dbg_register <v4l2-dbg-register>` except for ``size`` and | |
54 | call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The | |
55 | ``match.type`` and ``match.addr`` or ``match.name`` fields select a chip | |
56 | on the TV card, the ``reg`` field specifies a register number and the | |
57 | ``val`` field the value to be written into the register. | |
58 | ||
59 | To read a register applications must initialize the ``match.type``, | |
60 | ``match.addr`` or ``match.name`` and ``reg`` fields, and call | |
61 | ``VIDIOC_DBG_G_REGISTER`` with a pointer to this structure. On success | |
62 | the driver stores the register value in the ``val`` field and the size | |
63 | (in bytes) of the value in ``size``. | |
64 | ||
65 | When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr`` | |
66 | selects the nth non-sub-device chip on the TV card. The number zero | |
67 | always selects the host chip, e. g. the chip connected to the PCI or USB | |
68 | bus. You can find out which chips are present with the | |
7347081e | 69 | :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl. |
5377d91f MH |
70 | |
71 | When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr`` | |
72 | selects the nth sub-device. | |
73 | ||
74 | These ioctls are optional, not all drivers may support them. However | |
75 | when a driver supports these ioctls it must also support | |
7347081e | 76 | :ref:`VIDIOC_DBG_G_CHIP_INFO`. Conversely |
5377d91f MH |
77 | it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls. |
78 | ||
79 | ``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced | |
80 | in Linux 2.6.21, but their API was changed to the one described here in | |
81 | kernel 2.6.29. | |
82 | ||
83 | We recommended the v4l2-dbg utility over calling these ioctls directly. | |
84 | It is available from the LinuxTV v4l-dvb repository; see | |
85 | `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access | |
86 | instructions. | |
87 | ||
88 | ||
89 | .. _v4l2-dbg-match: | |
90 | ||
91 | .. flat-table:: struct v4l2_dbg_match | |
92 | :header-rows: 0 | |
93 | :stub-columns: 0 | |
94 | :widths: 1 1 1 2 | |
95 | ||
96 | ||
97 | - .. row 1 | |
98 | ||
99 | - __u32 | |
100 | ||
101 | - ``type`` | |
102 | ||
103 | - See :ref:`chip-match-types` for a list of possible types. | |
104 | ||
105 | - .. row 2 | |
106 | ||
107 | - union | |
108 | ||
109 | - (anonymous) | |
110 | ||
111 | - .. row 3 | |
112 | ||
0579e6e3 | 113 | - |
5377d91f MH |
114 | - __u32 |
115 | ||
116 | - ``addr`` | |
117 | ||
118 | - Match a chip by this number, interpreted according to the ``type`` | |
0579e6e3 | 119 | field. |
5377d91f MH |
120 | |
121 | - .. row 4 | |
122 | ||
0579e6e3 | 123 | - |
5377d91f MH |
124 | - char |
125 | ||
126 | - ``name[32]`` | |
127 | ||
128 | - Match a chip by this name, interpreted according to the ``type`` | |
0579e6e3 | 129 | field. Currently unused. |
5377d91f MH |
130 | |
131 | ||
132 | ||
133 | .. _v4l2-dbg-register: | |
134 | ||
135 | .. flat-table:: struct v4l2_dbg_register | |
136 | :header-rows: 0 | |
137 | :stub-columns: 0 | |
138 | ||
139 | ||
140 | - .. row 1 | |
141 | ||
142 | - struct v4l2_dbg_match | |
143 | ||
144 | - ``match`` | |
145 | ||
146 | - How to match the chip, see :ref:`v4l2-dbg-match`. | |
147 | ||
148 | - .. row 2 | |
149 | ||
150 | - __u32 | |
151 | ||
152 | - ``size`` | |
153 | ||
154 | - The register size in bytes. | |
155 | ||
156 | - .. row 3 | |
157 | ||
158 | - __u64 | |
159 | ||
160 | - ``reg`` | |
161 | ||
162 | - A register number. | |
163 | ||
164 | - .. row 4 | |
165 | ||
166 | - __u64 | |
167 | ||
168 | - ``val`` | |
169 | ||
170 | - The value read from, or to be written into the register. | |
171 | ||
172 | ||
173 | ||
174 | .. _chip-match-types: | |
175 | ||
176 | .. flat-table:: Chip Match Types | |
177 | :header-rows: 0 | |
178 | :stub-columns: 0 | |
179 | :widths: 3 1 4 | |
180 | ||
181 | ||
182 | - .. row 1 | |
183 | ||
184 | - ``V4L2_CHIP_MATCH_BRIDGE`` | |
185 | ||
186 | - 0 | |
187 | ||
188 | - Match the nth chip on the card, zero for the bridge chip. Does not | |
0579e6e3 | 189 | match sub-devices. |
5377d91f MH |
190 | |
191 | - .. row 2 | |
192 | ||
193 | - ``V4L2_CHIP_MATCH_SUBDEV`` | |
194 | ||
195 | - 4 | |
196 | ||
197 | - Match the nth sub-device. | |
198 | ||
199 | ||
15e7d615 | 200 | Return Value |
5377d91f MH |
201 | ============ |
202 | ||
203 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
204 | appropriately. The generic error codes are described at the | |
205 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
206 | ||
207 | EPERM | |
208 | Insufficient permissions. Root privileges are required to execute | |
209 | these ioctls. |