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 | ||
b7e67f6c | 18 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_ext_controls *argp ) |
5377d91f | 19 | |
586027ce | 20 | |
15e7d615 | 21 | Arguments |
5377d91f MH |
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 | ||
15e7d615 | 34 | Description |
5377d91f MH |
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 | |
cdb4af0f | 57 | set ``size`` to a valid value and return an ``ENOSPC`` error code. You |
5377d91f MH |
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 | ||
cdb4af0f | 84 | When the ``id`` or ``which`` is invalid drivers return an ``EINVAL`` error |
5377d91f | 85 | code. When the value is out of bounds drivers can choose to take the |
cdb4af0f | 86 | closest valid value or return an ``ERANGE`` error code, whatever seems more |
5377d91f MH |
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 | |
cdb4af0f | 90 | control), then this will also result in an ``EINVAL`` error code error. |
5377d91f MH |
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 | ||
0579e6e3 | 112 | - |
5377d91f MH |
113 | - Identifies the control, set by the application. |
114 | ||
115 | - .. row 2 | |
116 | ||
117 | - __u32 | |
118 | ||
119 | - ``size`` | |
120 | ||
0579e6e3 | 121 | - |
5377d91f | 122 | - The total size in bytes of the payload of this control. This is |
0579e6e3 MCC |
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 | |
125 | the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is | |
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 | |
706f8a99 MCC |
128 | returned. |
129 | ||
130 | .. note:: For string controls, this ``size`` field should | |
131 | not be confused with the length of the string. This field refers | |
132 | to the size of the memory that contains the string. The actual | |
133 | *length* of the string may well be much smaller. | |
5377d91f MH |
134 | |
135 | - .. row 3 | |
136 | ||
137 | - __u32 | |
138 | ||
139 | - ``reserved2``\ [1] | |
140 | ||
0579e6e3 | 141 | - |
5377d91f | 142 | - Reserved for future extensions. Drivers and applications must set |
0579e6e3 | 143 | the array to zero. |
5377d91f MH |
144 | |
145 | - .. row 4 | |
146 | ||
147 | - union | |
148 | ||
149 | - (anonymous) | |
150 | ||
151 | - .. row 5 | |
152 | ||
0579e6e3 | 153 | - |
5377d91f MH |
154 | - __s32 |
155 | ||
156 | - ``value`` | |
157 | ||
158 | - New value or current value. Valid if this control is not of type | |
0579e6e3 MCC |
159 | ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is |
160 | not set. | |
5377d91f MH |
161 | |
162 | - .. row 6 | |
163 | ||
0579e6e3 | 164 | - |
5377d91f MH |
165 | - __s64 |
166 | ||
167 | - ``value64`` | |
168 | ||
169 | - New value or current value. Valid if this control is of type | |
0579e6e3 MCC |
170 | ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is |
171 | not set. | |
5377d91f MH |
172 | |
173 | - .. row 7 | |
174 | ||
0579e6e3 | 175 | - |
5377d91f MH |
176 | - char * |
177 | ||
178 | - ``string`` | |
179 | ||
180 | - A pointer to a string. Valid if this control is of type | |
0579e6e3 | 181 | ``V4L2_CTRL_TYPE_STRING``. |
5377d91f MH |
182 | |
183 | - .. row 8 | |
184 | ||
0579e6e3 | 185 | - |
5377d91f MH |
186 | - __u8 * |
187 | ||
188 | - ``p_u8`` | |
189 | ||
190 | - A pointer to a matrix control of unsigned 8-bit values. Valid if | |
0579e6e3 | 191 | this control is of type ``V4L2_CTRL_TYPE_U8``. |
5377d91f MH |
192 | |
193 | - .. row 9 | |
194 | ||
0579e6e3 | 195 | - |
5377d91f MH |
196 | - __u16 * |
197 | ||
198 | - ``p_u16`` | |
199 | ||
200 | - A pointer to a matrix control of unsigned 16-bit values. Valid if | |
0579e6e3 | 201 | this control is of type ``V4L2_CTRL_TYPE_U16``. |
5377d91f MH |
202 | |
203 | - .. row 10 | |
204 | ||
0579e6e3 | 205 | - |
5377d91f MH |
206 | - __u32 * |
207 | ||
208 | - ``p_u32`` | |
209 | ||
210 | - A pointer to a matrix control of unsigned 32-bit values. Valid if | |
0579e6e3 | 211 | this control is of type ``V4L2_CTRL_TYPE_U32``. |
5377d91f MH |
212 | |
213 | - .. row 11 | |
214 | ||
0579e6e3 | 215 | - |
5377d91f MH |
216 | - void * |
217 | ||
218 | - ``ptr`` | |
219 | ||
220 | - A pointer to a compound type which can be an N-dimensional array | |
0579e6e3 MCC |
221 | and/or a compound type (the control's type is >= |
222 | ``V4L2_CTRL_COMPOUND_TYPES``). Valid if | |
223 | ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set for this control. | |
5377d91f MH |
224 | |
225 | ||
226 | ||
227 | .. _v4l2-ext-controls: | |
228 | ||
229 | .. flat-table:: struct v4l2_ext_controls | |
230 | :header-rows: 0 | |
231 | :stub-columns: 0 | |
232 | :widths: 1 1 2 1 | |
233 | ||
234 | ||
235 | - .. row 1 | |
236 | ||
237 | - union | |
238 | ||
239 | - (anonymous) | |
240 | ||
241 | - .. row 2 | |
242 | ||
0579e6e3 | 243 | - |
5377d91f MH |
244 | - __u32 |
245 | ||
246 | - ``ctrl_class`` | |
247 | ||
248 | - The control class to which all controls belong, see | |
0579e6e3 MCC |
249 | :ref:`ctrl-class`. Drivers that use a kernel framework for |
250 | handling controls will also accept a value of 0 here, meaning that | |
251 | the controls can belong to any control class. Whether drivers | |
252 | support this can be tested by setting ``ctrl_class`` to 0 and | |
253 | calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that | |
254 | succeeds, then the driver supports this feature. | |
5377d91f MH |
255 | |
256 | - .. row 3 | |
257 | ||
0579e6e3 | 258 | - |
5377d91f MH |
259 | - __u32 |
260 | ||
261 | - ``which`` | |
262 | ||
263 | - Which value of the control to get/set/try. | |
0579e6e3 MCC |
264 | ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the |
265 | control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default | |
706f8a99 MCC |
266 | value of the control. |
267 | ||
268 | .. note:: You can only get the default value of the control, | |
269 | you cannot set or try it. | |
0579e6e3 MCC |
270 | |
271 | For backwards compatibility you can also use a control class here | |
272 | (see :ref:`ctrl-class`). In that case all controls have to | |
273 | belong to that control class. This usage is deprecated, instead | |
274 | just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old | |
275 | drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and | |
276 | that require a control class here. You can test for such drivers | |
277 | by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling | |
278 | VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the | |
279 | driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. | |
5377d91f MH |
280 | |
281 | - .. row 4 | |
282 | ||
283 | - __u32 | |
284 | ||
285 | - ``count`` | |
286 | ||
287 | - The number of controls in the controls array. May also be zero. | |
288 | ||
289 | - .. row 5 | |
290 | ||
291 | - __u32 | |
292 | ||
293 | - ``error_idx`` | |
294 | ||
295 | - Set by the driver in case of an error. If the error is associated | |
0579e6e3 MCC |
296 | with a particular control, then ``error_idx`` is set to the index |
297 | of that control. If the error is not related to a specific | |
298 | control, or the validation step failed (see below), then | |
299 | ``error_idx`` is set to ``count``. The value is undefined if the | |
300 | ioctl returned 0 (success). | |
301 | ||
302 | Before controls are read from/written to hardware a validation | |
303 | step takes place: this checks if all controls in the list are | |
304 | valid controls, if no attempt is made to write to a read-only | |
305 | control or read from a write-only control, and any other up-front | |
306 | checks that can be done without accessing the hardware. The exact | |
307 | validations done during this step are driver dependent since some | |
308 | checks might require hardware access for some devices, thus making | |
309 | it impossible to do those checks up-front. However, drivers should | |
310 | make a best-effort to do as many up-front checks as possible. | |
311 | ||
312 | This check is done to avoid leaving the hardware in an | |
313 | inconsistent state due to easy-to-avoid problems. But it leads to | |
314 | another problem: the application needs to know whether an error | |
315 | came from the validation step (meaning that the hardware was not | |
316 | touched) or from an error during the actual reading from/writing | |
317 | to hardware. | |
318 | ||
319 | The, in hindsight quite poor, solution for that is to set | |
320 | ``error_idx`` to ``count`` if the validation failed. This has the | |
321 | unfortunate side-effect that it is not possible to see which | |
322 | control failed the validation. If the validation was successful | |
323 | and the error happened while accessing the hardware, then | |
324 | ``error_idx`` is less than ``count`` and only the controls up to | |
325 | ``error_idx-1`` were read or written correctly, and the state of | |
326 | the remaining controls is undefined. | |
327 | ||
328 | Since :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` does not access hardware there is | |
329 | also no need to handle the validation step in this special way, so | |
330 | ``error_idx`` will just be set to the control that failed the | |
331 | validation step instead of to ``count``. This means that if | |
332 | :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` fails with ``error_idx`` set to ``count``, | |
333 | then you can call :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` to try to discover the | |
334 | actual control that failed the validation step. Unfortunately, | |
335 | there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. | |
5377d91f MH |
336 | |
337 | - .. row 6 | |
338 | ||
339 | - __u32 | |
340 | ||
341 | - ``reserved``\ [2] | |
342 | ||
343 | - Reserved for future extensions. Drivers and applications must set | |
0579e6e3 | 344 | the array to zero. |
5377d91f MH |
345 | |
346 | - .. row 7 | |
347 | ||
348 | - struct :ref:`v4l2_ext_control <v4l2-ext-control>` * | |
349 | ||
350 | - ``controls`` | |
351 | ||
352 | - Pointer to an array of ``count`` v4l2_ext_control structures. | |
0579e6e3 | 353 | Ignored if ``count`` equals zero. |
5377d91f MH |
354 | |
355 | ||
356 | ||
357 | .. _ctrl-class: | |
358 | ||
359 | .. flat-table:: Control classes | |
360 | :header-rows: 0 | |
361 | :stub-columns: 0 | |
362 | :widths: 3 1 4 | |
363 | ||
364 | ||
365 | - .. row 1 | |
366 | ||
367 | - ``V4L2_CTRL_CLASS_USER`` | |
368 | ||
369 | - 0x980000 | |
370 | ||
371 | - The class containing user controls. These controls are described | |
0579e6e3 MCC |
372 | in :ref:`control`. All controls that can be set using the |
373 | :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and | |
374 | :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this | |
375 | class. | |
5377d91f MH |
376 | |
377 | - .. row 2 | |
378 | ||
379 | - ``V4L2_CTRL_CLASS_MPEG`` | |
380 | ||
381 | - 0x990000 | |
382 | ||
383 | - The class containing MPEG compression controls. These controls are | |
0579e6e3 | 384 | described in :ref:`mpeg-controls`. |
5377d91f MH |
385 | |
386 | - .. row 3 | |
387 | ||
388 | - ``V4L2_CTRL_CLASS_CAMERA`` | |
389 | ||
390 | - 0x9a0000 | |
391 | ||
392 | - The class containing camera controls. These controls are described | |
0579e6e3 | 393 | in :ref:`camera-controls`. |
5377d91f MH |
394 | |
395 | - .. row 4 | |
396 | ||
397 | - ``V4L2_CTRL_CLASS_FM_TX`` | |
398 | ||
399 | - 0x9b0000 | |
400 | ||
401 | - The class containing FM Transmitter (FM TX) controls. These | |
0579e6e3 | 402 | controls are described in :ref:`fm-tx-controls`. |
5377d91f MH |
403 | |
404 | - .. row 5 | |
405 | ||
406 | - ``V4L2_CTRL_CLASS_FLASH`` | |
407 | ||
408 | - 0x9c0000 | |
409 | ||
410 | - The class containing flash device controls. These controls are | |
0579e6e3 | 411 | described in :ref:`flash-controls`. |
5377d91f MH |
412 | |
413 | - .. row 6 | |
414 | ||
415 | - ``V4L2_CTRL_CLASS_JPEG`` | |
416 | ||
417 | - 0x9d0000 | |
418 | ||
419 | - The class containing JPEG compression controls. These controls are | |
0579e6e3 | 420 | described in :ref:`jpeg-controls`. |
5377d91f MH |
421 | |
422 | - .. row 7 | |
423 | ||
424 | - ``V4L2_CTRL_CLASS_IMAGE_SOURCE`` | |
425 | ||
426 | - 0x9e0000 | |
427 | ||
428 | - The class containing image source controls. These controls are | |
0579e6e3 | 429 | described in :ref:`image-source-controls`. |
5377d91f MH |
430 | |
431 | - .. row 8 | |
432 | ||
433 | - ``V4L2_CTRL_CLASS_IMAGE_PROC`` | |
434 | ||
435 | - 0x9f0000 | |
436 | ||
437 | - The class containing image processing controls. These controls are | |
0579e6e3 | 438 | described in :ref:`image-process-controls`. |
5377d91f MH |
439 | |
440 | - .. row 9 | |
441 | ||
442 | - ``V4L2_CTRL_CLASS_FM_RX`` | |
443 | ||
444 | - 0xa10000 | |
445 | ||
446 | - The class containing FM Receiver (FM RX) controls. These controls | |
0579e6e3 | 447 | are described in :ref:`fm-rx-controls`. |
5377d91f MH |
448 | |
449 | - .. row 10 | |
450 | ||
451 | - ``V4L2_CTRL_CLASS_RF_TUNER`` | |
452 | ||
453 | - 0xa20000 | |
454 | ||
455 | - The class containing RF tuner controls. These controls are | |
0579e6e3 | 456 | described in :ref:`rf-tuner-controls`. |
5377d91f MH |
457 | |
458 | ||
15e7d615 | 459 | Return Value |
5377d91f MH |
460 | ============ |
461 | ||
462 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
463 | appropriately. The generic error codes are described at the | |
464 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
465 | ||
466 | EINVAL | |
467 | The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``id`` is | |
468 | invalid, the struct :ref:`v4l2_ext_controls <v4l2-ext-controls>` | |
469 | ``which`` is invalid, or the struct | |
470 | :ref:`v4l2_ext_control <v4l2-ext-control>` ``value`` was | |
471 | inappropriate (e.g. the given menu index is not supported by the | |
472 | driver). This error code is also returned by the | |
2212ff25 | 473 | :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 |
474 | more control values are in conflict. |
475 | ||
476 | ERANGE | |
477 | The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``value`` | |
478 | is out of bounds. | |
479 | ||
480 | EBUSY | |
481 | The control is temporarily not changeable, possibly because another | |
482 | applications took over control of the device function this control | |
483 | belongs to. | |
484 | ||
485 | ENOSPC | |
486 | The space reserved for the control's payload is insufficient. The | |
487 | field ``size`` is set to a value that is enough to store the payload | |
488 | and this error code is returned. | |
489 | ||
490 | EACCES | |
491 | Attempt to try or set a read-only control or to get a write-only | |
492 | control. |