Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_G_EXT_CTRLS: |
5377d91f MH |
4 | |
5 | ****************************************************************** | |
6 | ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS | |
7 | ****************************************************************** | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_G_EXT_CTRLS - VIDIOC_S_EXT_CTRLS - VIDIOC_TRY_EXT_CTRLS - Get or set the value of several controls, try control values |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
41d80465 MCC |
18 | .. c:function:: int ioctl( int fd, VIDIOC_G_EXT_CTRLS, struct v4l2_ext_controls *argp ) |
19 | :name: VIDIOC_G_EXT_CTRLS | |
20 | ||
21 | ||
22 | .. c:function:: int ioctl( int fd, VIDIOC_S_EXT_CTRLS, struct v4l2_ext_controls *argp ) | |
23 | :name: VIDIOC_S_EXT_CTRLS | |
24 | ||
25 | ||
26 | .. c:function:: int ioctl( int fd, VIDIOC_TRY_EXT_CTRLS, struct v4l2_ext_controls *argp ) | |
27 | :name: VIDIOC_TRY_EXT_CTRLS | |
5377d91f | 28 | |
586027ce | 29 | |
15e7d615 | 30 | Arguments |
5377d91f MH |
31 | ========= |
32 | ||
33 | ``fd`` | |
34 | File descriptor returned by :ref:`open() <func-open>`. | |
35 | ||
5377d91f MH |
36 | ``argp`` |
37 | ||
38 | ||
15e7d615 | 39 | Description |
5377d91f MH |
40 | =========== |
41 | ||
42 | These ioctls allow the caller to get or set multiple controls | |
43 | atomically. Control IDs are grouped into control classes (see | |
44 | :ref:`ctrl-class`) and all controls in the control array must belong | |
45 | to the same control class. | |
46 | ||
47 | Applications must always fill in the ``count``, ``which``, ``controls`` | |
48 | and ``reserved`` fields of struct | |
e8be7e97 MCC |
49 | :c:type:`v4l2_ext_controls`, and initialize the |
50 | struct :c:type:`v4l2_ext_control` array pointed to | |
5377d91f MH |
51 | by the ``controls`` fields. |
52 | ||
53 | To get the current value of a set of controls applications initialize | |
54 | the ``id``, ``size`` and ``reserved2`` fields of each struct | |
e8be7e97 | 55 | :c:type:`v4l2_ext_control` and call the |
4e03cb76 | 56 | :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls controls must also set the |
5377d91f MH |
57 | ``string`` field. Controls of compound types |
58 | (``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field. | |
59 | ||
60 | If the ``size`` is too small to receive the control result (only | |
61 | relevant for pointer-type controls like strings), then the driver will | |
cdb4af0f | 62 | set ``size`` to a valid value and return an ``ENOSPC`` error code. You |
5377d91f MH |
63 | should re-allocate the memory to this new size and try again. For the |
64 | string type it is possible that the same issue occurs again if the | |
65 | string has grown in the meantime. It is recommended to call | |
7347081e | 66 | :ref:`VIDIOC_QUERYCTRL` first and use |
5377d91f MH |
67 | ``maximum``\ +1 as the new ``size`` value. It is guaranteed that that is |
68 | sufficient memory. | |
69 | ||
70 | N-dimensional arrays are set and retrieved row-by-row. You cannot set a | |
71 | partial array, all elements have to be set or retrieved. The total size | |
72 | is calculated as ``elems`` * ``elem_size``. These values can be obtained | |
af4a4d0d | 73 | by calling :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`. |
5377d91f MH |
74 | |
75 | To change the value of a set of controls applications initialize the | |
76 | ``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields | |
e8be7e97 | 77 | of each struct :c:type:`v4l2_ext_control` and call |
2212ff25 | 78 | the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. The controls will only be set if *all* |
5377d91f MH |
79 | control values are valid. |
80 | ||
81 | To check if a set of controls have correct values applications | |
82 | initialize the ``id``, ``size``, ``reserved2`` and | |
83 | ``value/value64/string/ptr`` fields of each struct | |
e8be7e97 | 84 | :c:type:`v4l2_ext_control` and call the |
2212ff25 | 85 | :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. It is up to the driver whether wrong |
5377d91f MH |
86 | values are automatically adjusted to a valid value or if an error is |
87 | returned. | |
88 | ||
cdb4af0f | 89 | When the ``id`` or ``which`` is invalid drivers return an ``EINVAL`` error |
5377d91f | 90 | code. When the value is out of bounds drivers can choose to take the |
cdb4af0f | 91 | closest valid value or return an ``ERANGE`` error code, whatever seems more |
5377d91f | 92 | appropriate. In the first case the new value is set in struct |
e8be7e97 | 93 | :c:type:`v4l2_ext_control`. If the new control value |
5377d91f | 94 | is inappropriate (e.g. the given menu index is not supported by the menu |
cdb4af0f | 95 | control), then this will also result in an ``EINVAL`` error code error. |
5377d91f MH |
96 | |
97 | The driver will only set/get these controls if all control values are | |
98 | correct. This prevents the situation where only some of the controls | |
99 | were set/get. Only low-level errors (e. g. a failed i2c command) can | |
100 | still cause this situation. | |
101 | ||
102 | ||
ef76c068 MCC |
103 | .. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{1.5cm}|p{11.8cm}| |
104 | ||
e8be7e97 | 105 | .. c:type:: v4l2_ext_control |
fa92b04d | 106 | |
ef76c068 | 107 | .. cssclass: longtable |
5bd4bb78 | 108 | |
5377d91f MH |
109 | .. flat-table:: struct v4l2_ext_control |
110 | :header-rows: 0 | |
111 | :stub-columns: 0 | |
112 | :widths: 1 1 1 2 | |
113 | ||
114 | ||
115 | - .. row 1 | |
116 | ||
117 | - __u32 | |
118 | ||
119 | - ``id`` | |
120 | ||
0579e6e3 | 121 | - |
5377d91f MH |
122 | - Identifies the control, set by the application. |
123 | ||
124 | - .. row 2 | |
125 | ||
126 | - __u32 | |
127 | ||
128 | - ``size`` | |
129 | ||
0579e6e3 | 130 | - |
5377d91f | 131 | - The total size in bytes of the payload of this control. This is |
0579e6e3 MCC |
132 | normally 0, but for pointer controls this should be set to the |
133 | size of the memory containing the payload, or that will receive | |
134 | the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is | |
135 | less than is required to store the payload result, then it is set | |
136 | to a value large enough to store the payload result and ``ENOSPC`` is | |
706f8a99 MCC |
137 | returned. |
138 | ||
b6b6e678 MCC |
139 | .. note:: |
140 | ||
141 | For string controls, this ``size`` field should | |
706f8a99 MCC |
142 | not be confused with the length of the string. This field refers |
143 | to the size of the memory that contains the string. The actual | |
144 | *length* of the string may well be much smaller. | |
5377d91f MH |
145 | |
146 | - .. row 3 | |
147 | ||
148 | - __u32 | |
149 | ||
8968da9b | 150 | - ``reserved2``\ [1] |
5377d91f | 151 | |
0579e6e3 | 152 | - |
5377d91f | 153 | - Reserved for future extensions. Drivers and applications must set |
0579e6e3 | 154 | the array to zero. |
5377d91f MH |
155 | |
156 | - .. row 4 | |
157 | ||
158 | - union | |
159 | ||
160 | - (anonymous) | |
161 | ||
162 | - .. row 5 | |
163 | ||
0579e6e3 | 164 | - |
5377d91f MH |
165 | - __s32 |
166 | ||
167 | - ``value`` | |
168 | ||
169 | - New value or current value. Valid if this control is not of type | |
0579e6e3 MCC |
170 | ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is |
171 | not set. | |
5377d91f MH |
172 | |
173 | - .. row 6 | |
174 | ||
0579e6e3 | 175 | - |
5377d91f MH |
176 | - __s64 |
177 | ||
178 | - ``value64`` | |
179 | ||
180 | - New value or current value. Valid if this control is of type | |
0579e6e3 MCC |
181 | ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is |
182 | not set. | |
5377d91f MH |
183 | |
184 | - .. row 7 | |
185 | ||
0579e6e3 | 186 | - |
5377d91f MH |
187 | - char * |
188 | ||
189 | - ``string`` | |
190 | ||
191 | - A pointer to a string. Valid if this control is of type | |
0579e6e3 | 192 | ``V4L2_CTRL_TYPE_STRING``. |
5377d91f MH |
193 | |
194 | - .. row 8 | |
195 | ||
0579e6e3 | 196 | - |
5377d91f MH |
197 | - __u8 * |
198 | ||
199 | - ``p_u8`` | |
200 | ||
201 | - A pointer to a matrix control of unsigned 8-bit values. Valid if | |
0579e6e3 | 202 | this control is of type ``V4L2_CTRL_TYPE_U8``. |
5377d91f MH |
203 | |
204 | - .. row 9 | |
205 | ||
0579e6e3 | 206 | - |
5377d91f MH |
207 | - __u16 * |
208 | ||
209 | - ``p_u16`` | |
210 | ||
211 | - A pointer to a matrix control of unsigned 16-bit values. Valid if | |
0579e6e3 | 212 | this control is of type ``V4L2_CTRL_TYPE_U16``. |
5377d91f MH |
213 | |
214 | - .. row 10 | |
215 | ||
0579e6e3 | 216 | - |
5377d91f MH |
217 | - __u32 * |
218 | ||
219 | - ``p_u32`` | |
220 | ||
221 | - A pointer to a matrix control of unsigned 32-bit values. Valid if | |
0579e6e3 | 222 | this control is of type ``V4L2_CTRL_TYPE_U32``. |
5377d91f MH |
223 | |
224 | - .. row 11 | |
225 | ||
0579e6e3 | 226 | - |
5377d91f MH |
227 | - void * |
228 | ||
229 | - ``ptr`` | |
230 | ||
231 | - A pointer to a compound type which can be an N-dimensional array | |
0579e6e3 MCC |
232 | and/or a compound type (the control's type is >= |
233 | ``V4L2_CTRL_COMPOUND_TYPES``). Valid if | |
234 | ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set for this control. | |
5377d91f MH |
235 | |
236 | ||
43e4138b | 237 | .. tabularcolumns:: |p{4.0cm}|p{2.0cm}|p{2.0cm}|p{8.5cm}| |
5377d91f | 238 | |
e8be7e97 | 239 | .. c:type:: v4l2_ext_controls |
5377d91f | 240 | |
ef76c068 | 241 | .. cssclass:: longtable |
5bd4bb78 | 242 | |
5377d91f MH |
243 | .. flat-table:: struct v4l2_ext_controls |
244 | :header-rows: 0 | |
245 | :stub-columns: 0 | |
246 | :widths: 1 1 2 1 | |
247 | ||
248 | ||
249 | - .. row 1 | |
250 | ||
251 | - union | |
252 | ||
253 | - (anonymous) | |
254 | ||
255 | - .. row 2 | |
256 | ||
0579e6e3 | 257 | - |
5377d91f MH |
258 | - __u32 |
259 | ||
260 | - ``ctrl_class`` | |
261 | ||
262 | - The control class to which all controls belong, see | |
0579e6e3 MCC |
263 | :ref:`ctrl-class`. Drivers that use a kernel framework for |
264 | handling controls will also accept a value of 0 here, meaning that | |
265 | the controls can belong to any control class. Whether drivers | |
266 | support this can be tested by setting ``ctrl_class`` to 0 and | |
267 | calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that | |
268 | succeeds, then the driver supports this feature. | |
5377d91f MH |
269 | |
270 | - .. row 3 | |
271 | ||
0579e6e3 | 272 | - |
5377d91f MH |
273 | - __u32 |
274 | ||
275 | - ``which`` | |
276 | ||
277 | - Which value of the control to get/set/try. | |
0579e6e3 MCC |
278 | ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the |
279 | control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default | |
706f8a99 MCC |
280 | value of the control. |
281 | ||
b6b6e678 MCC |
282 | .. note:: |
283 | ||
284 | You can only get the default value of the control, | |
706f8a99 | 285 | you cannot set or try it. |
0579e6e3 MCC |
286 | |
287 | For backwards compatibility you can also use a control class here | |
288 | (see :ref:`ctrl-class`). In that case all controls have to | |
289 | belong to that control class. This usage is deprecated, instead | |
290 | just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old | |
291 | drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and | |
292 | that require a control class here. You can test for such drivers | |
293 | by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling | |
294 | VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the | |
295 | driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. | |
5377d91f MH |
296 | |
297 | - .. row 4 | |
298 | ||
299 | - __u32 | |
300 | ||
301 | - ``count`` | |
302 | ||
303 | - The number of controls in the controls array. May also be zero. | |
304 | ||
305 | - .. row 5 | |
306 | ||
307 | - __u32 | |
308 | ||
309 | - ``error_idx`` | |
310 | ||
311 | - Set by the driver in case of an error. If the error is associated | |
0579e6e3 MCC |
312 | with a particular control, then ``error_idx`` is set to the index |
313 | of that control. If the error is not related to a specific | |
314 | control, or the validation step failed (see below), then | |
315 | ``error_idx`` is set to ``count``. The value is undefined if the | |
316 | ioctl returned 0 (success). | |
317 | ||
318 | Before controls are read from/written to hardware a validation | |
319 | step takes place: this checks if all controls in the list are | |
320 | valid controls, if no attempt is made to write to a read-only | |
321 | control or read from a write-only control, and any other up-front | |
322 | checks that can be done without accessing the hardware. The exact | |
323 | validations done during this step are driver dependent since some | |
324 | checks might require hardware access for some devices, thus making | |
325 | it impossible to do those checks up-front. However, drivers should | |
326 | make a best-effort to do as many up-front checks as possible. | |
327 | ||
328 | This check is done to avoid leaving the hardware in an | |
329 | inconsistent state due to easy-to-avoid problems. But it leads to | |
330 | another problem: the application needs to know whether an error | |
331 | came from the validation step (meaning that the hardware was not | |
332 | touched) or from an error during the actual reading from/writing | |
333 | to hardware. | |
334 | ||
335 | The, in hindsight quite poor, solution for that is to set | |
336 | ``error_idx`` to ``count`` if the validation failed. This has the | |
337 | unfortunate side-effect that it is not possible to see which | |
338 | control failed the validation. If the validation was successful | |
339 | and the error happened while accessing the hardware, then | |
340 | ``error_idx`` is less than ``count`` and only the controls up to | |
341 | ``error_idx-1`` were read or written correctly, and the state of | |
342 | the remaining controls is undefined. | |
343 | ||
344 | Since :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` does not access hardware there is | |
345 | also no need to handle the validation step in this special way, so | |
346 | ``error_idx`` will just be set to the control that failed the | |
347 | validation step instead of to ``count``. This means that if | |
348 | :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` fails with ``error_idx`` set to ``count``, | |
349 | then you can call :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` to try to discover the | |
350 | actual control that failed the validation step. Unfortunately, | |
351 | there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. | |
5377d91f MH |
352 | |
353 | - .. row 6 | |
354 | ||
355 | - __u32 | |
356 | ||
8968da9b | 357 | - ``reserved``\ [2] |
5377d91f | 358 | |
ef76c068 MCC |
359 | - Reserved for future extensions. |
360 | ||
361 | Drivers and applications must set the array to zero. | |
5377d91f MH |
362 | |
363 | - .. row 7 | |
364 | ||
e8be7e97 | 365 | - struct :c:type:`v4l2_ext_control` * |
5377d91f MH |
366 | |
367 | - ``controls`` | |
368 | ||
369 | - Pointer to an array of ``count`` v4l2_ext_control structures. | |
ef76c068 | 370 | |
0579e6e3 | 371 | Ignored if ``count`` equals zero. |
5377d91f MH |
372 | |
373 | ||
fa92b04d | 374 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
5377d91f MH |
375 | |
376 | .. _ctrl-class: | |
377 | ||
378 | .. flat-table:: Control classes | |
379 | :header-rows: 0 | |
380 | :stub-columns: 0 | |
381 | :widths: 3 1 4 | |
382 | ||
383 | ||
384 | - .. row 1 | |
385 | ||
386 | - ``V4L2_CTRL_CLASS_USER`` | |
387 | ||
388 | - 0x980000 | |
389 | ||
390 | - The class containing user controls. These controls are described | |
0579e6e3 MCC |
391 | in :ref:`control`. All controls that can be set using the |
392 | :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and | |
393 | :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this | |
394 | class. | |
5377d91f MH |
395 | |
396 | - .. row 2 | |
397 | ||
398 | - ``V4L2_CTRL_CLASS_MPEG`` | |
399 | ||
400 | - 0x990000 | |
401 | ||
402 | - The class containing MPEG compression controls. These controls are | |
0579e6e3 | 403 | described in :ref:`mpeg-controls`. |
5377d91f MH |
404 | |
405 | - .. row 3 | |
406 | ||
407 | - ``V4L2_CTRL_CLASS_CAMERA`` | |
408 | ||
409 | - 0x9a0000 | |
410 | ||
411 | - The class containing camera controls. These controls are described | |
0579e6e3 | 412 | in :ref:`camera-controls`. |
5377d91f MH |
413 | |
414 | - .. row 4 | |
415 | ||
416 | - ``V4L2_CTRL_CLASS_FM_TX`` | |
417 | ||
418 | - 0x9b0000 | |
419 | ||
420 | - The class containing FM Transmitter (FM TX) controls. These | |
0579e6e3 | 421 | controls are described in :ref:`fm-tx-controls`. |
5377d91f MH |
422 | |
423 | - .. row 5 | |
424 | ||
425 | - ``V4L2_CTRL_CLASS_FLASH`` | |
426 | ||
427 | - 0x9c0000 | |
428 | ||
429 | - The class containing flash device controls. These controls are | |
0579e6e3 | 430 | described in :ref:`flash-controls`. |
5377d91f MH |
431 | |
432 | - .. row 6 | |
433 | ||
434 | - ``V4L2_CTRL_CLASS_JPEG`` | |
435 | ||
436 | - 0x9d0000 | |
437 | ||
438 | - The class containing JPEG compression controls. These controls are | |
0579e6e3 | 439 | described in :ref:`jpeg-controls`. |
5377d91f MH |
440 | |
441 | - .. row 7 | |
442 | ||
443 | - ``V4L2_CTRL_CLASS_IMAGE_SOURCE`` | |
444 | ||
445 | - 0x9e0000 | |
446 | ||
447 | - The class containing image source controls. These controls are | |
0579e6e3 | 448 | described in :ref:`image-source-controls`. |
5377d91f MH |
449 | |
450 | - .. row 8 | |
451 | ||
452 | - ``V4L2_CTRL_CLASS_IMAGE_PROC`` | |
453 | ||
454 | - 0x9f0000 | |
455 | ||
456 | - The class containing image processing controls. These controls are | |
0579e6e3 | 457 | described in :ref:`image-process-controls`. |
5377d91f MH |
458 | |
459 | - .. row 9 | |
460 | ||
461 | - ``V4L2_CTRL_CLASS_FM_RX`` | |
462 | ||
463 | - 0xa10000 | |
464 | ||
465 | - The class containing FM Receiver (FM RX) controls. These controls | |
0579e6e3 | 466 | are described in :ref:`fm-rx-controls`. |
5377d91f MH |
467 | |
468 | - .. row 10 | |
469 | ||
470 | - ``V4L2_CTRL_CLASS_RF_TUNER`` | |
471 | ||
472 | - 0xa20000 | |
473 | ||
474 | - The class containing RF tuner controls. These controls are | |
0579e6e3 | 475 | described in :ref:`rf-tuner-controls`. |
5377d91f MH |
476 | |
477 | ||
15e7d615 | 478 | Return Value |
5377d91f MH |
479 | ============ |
480 | ||
481 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
482 | appropriately. The generic error codes are described at the | |
483 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
484 | ||
485 | EINVAL | |
e8be7e97 MCC |
486 | The struct :c:type:`v4l2_ext_control` ``id`` is |
487 | invalid, the struct :c:type:`v4l2_ext_controls` | |
5377d91f | 488 | ``which`` is invalid, or the struct |
e8be7e97 | 489 | :c:type:`v4l2_ext_control` ``value`` was |
5377d91f MH |
490 | inappropriate (e.g. the given menu index is not supported by the |
491 | driver). This error code is also returned by the | |
2212ff25 | 492 | :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls if two or |
5377d91f MH |
493 | more control values are in conflict. |
494 | ||
495 | ERANGE | |
e8be7e97 | 496 | The struct :c:type:`v4l2_ext_control` ``value`` |
5377d91f MH |
497 | is out of bounds. |
498 | ||
499 | EBUSY | |
500 | The control is temporarily not changeable, possibly because another | |
501 | applications took over control of the device function this control | |
502 | belongs to. | |
503 | ||
504 | ENOSPC | |
505 | The space reserved for the control's payload is insufficient. The | |
506 | field ``size`` is set to a value that is enough to store the payload | |
507 | and this error code is returned. | |
508 | ||
509 | EACCES | |
510 | Attempt to try or set a read-only control or to get a write-only | |
511 | control. |