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