tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1.. -*- coding: utf-8; mode: rst -*-
2
3.. _VIDIOC_QUERYCTRL:
4
5*******************************************************************
6ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
7*******************************************************************
8
9Name
10====
11
12VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
13
14
15Synopsis
16========
17
18.. cpp:function:: int ioctl( int fd, int request, struct v4l2_queryctrl *argp )
19
20.. cpp:function:: int ioctl( int fd, int request, struct v4l2_query_ext_ctrl *argp )
21
22.. cpp:function:: int ioctl( int fd, int request, struct v4l2_querymenu *argp )
23
24
25Arguments
26=========
27
28``fd``
29 File descriptor returned by :ref:`open() <func-open>`.
30
31``request``
32 VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU
33
34``argp``
35
36
37Description
38===========
39
40To query the attributes of a control applications set the ``id`` field
41of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
42``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
43fills the rest of the structure or returns an ``EINVAL`` error code when the
44``id`` is invalid.
45
46It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
47with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
48exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
49this range is not supported. Further applications can enumerate private
50controls, which are not defined in this specification, by starting at
51``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
52returns ``EINVAL``.
53
54In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
55in the ``flags`` field this control is permanently disabled and should
56be ignored by the application. [#f1]_
57
58When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
59driver returns the next supported non-compound control, or ``EINVAL`` if
60there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
61can be specified to enumerate all compound controls (i.e. controls with
62type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
63controls that contain more than one value). Specify both
64``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
65order to enumerate all controls, compound or not. Drivers which do not
66support these flags yet always return ``EINVAL``.
67
68The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
69support controls that can use compound types, and to expose additional
70control information that cannot be returned in struct
71:ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
72
73``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
74``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
75as well.
76
77Additional information is required for menu controls: the names of the
78menu items. To query them applications set the ``id`` and ``index``
79fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
80``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
81fills the rest of the structure or returns an ``EINVAL`` error code when the
82``id`` or ``index`` is invalid. Menu items are enumerated by calling
83``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
84:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
85inclusive.
86
87.. note:: It is possible for ``VIDIOC_QUERYMENU`` to return
88 an ``EINVAL`` error code for some indices between ``minimum`` and
89 ``maximum``. In that case that particular menu item is not supported by
90 this driver. Also note that the ``minimum`` value is not necessarily 0.
91
92See also the examples in :ref:`control`.
93
94
95.. _v4l2-queryctrl:
96
97.. flat-table:: struct v4l2_queryctrl
98 :header-rows: 0
99 :stub-columns: 0
100 :widths: 1 1 2
101
102
103 - .. row 1
104
105 - __u32
106
107 - ``id``
108
109 - Identifies the control, set by the application. See
110 :ref:`control-id` for predefined IDs. When the ID is ORed with
111 V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
112 returns the first control with a higher ID. Drivers which do not
113 support this flag yet always return an ``EINVAL`` error code.
114
115 - .. row 2
116
117 - __u32
118
119 - ``type``
120
121 - Type of control, see :ref:`v4l2-ctrl-type`.
122
123 - .. row 3
124
125 - __u8
126
127 - ``name``\ [32]
128
129 - Name of the control, a NUL-terminated ASCII string. This
130 information is intended for the user.
131
132 - .. row 4
133
134 - __s32
135
136 - ``minimum``
137
138 - Minimum value, inclusive. This field gives a lower bound for the
139 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
140 the minimum value is to be used for each possible control type.
141 Note that this a signed 32-bit value.
142
143 - .. row 5
144
145 - __s32
146
147 - ``maximum``
148
149 - Maximum value, inclusive. This field gives an upper bound for the
150 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
151 the maximum value is to be used for each possible control type.
152 Note that this a signed 32-bit value.
153
154 - .. row 6
155
156 - __s32
157
158 - ``step``
159
160 - This field gives a step size for the control. See enum
161 :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
162 to be used for each possible control type. Note that this an
163 unsigned 32-bit value.
164
165 Generally drivers should not scale hardware control values. It may
166 be necessary for example when the ``name`` or ``id`` imply a
167 particular unit and the hardware actually accepts only multiples
168 of said unit. If so, drivers must take care values are properly
169 rounded when scaling, such that errors will not accumulate on
170 repeated read-write cycles.
171
172 This field gives the smallest change of an integer control
173 actually affecting hardware. Often the information is needed when
174 the user can change controls by keyboard or GUI buttons, rather
175 than a slider. When for example a hardware register accepts values
176 0-511 and the driver reports 0-65535, step should be 128.
177
178 Note that although signed, the step value is supposed to be always
179 positive.
180
181 - .. row 7
182
183 - __s32
184
185 - ``default_value``
186
187 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
188 ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
189 for other types of controls.
190
191 .. note:: Drivers reset controls to their default value only when
192 the driver is first loaded, never afterwards.
193
194 - .. row 8
195
196 - __u32
197
198 - ``flags``
199
200 - Control flags, see :ref:`control-flags`.
201
202 - .. row 9
203
204 - __u32
205
206 - ``reserved``\ [2]
207
208 - Reserved for future extensions. Drivers must set the array to
209 zero.
210
211
212
213.. _v4l2-query-ext-ctrl:
214
215.. flat-table:: struct v4l2_query_ext_ctrl
216 :header-rows: 0
217 :stub-columns: 0
218 :widths: 1 1 2
219
220
221 - .. row 1
222
223 - __u32
224
225 - ``id``
226
227 - Identifies the control, set by the application. See
228 :ref:`control-id` for predefined IDs. When the ID is ORed with
229 ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
230 returns the first non-compound control with a higher ID. When the
231 ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
232 the flag and returns the first compound control with a higher ID.
233 Set both to get the first control (compound or not) with a higher
234 ID.
235
236 - .. row 2
237
238 - __u32
239
240 - ``type``
241
242 - Type of control, see :ref:`v4l2-ctrl-type`.
243
244 - .. row 3
245
246 - char
247
248 - ``name``\ [32]
249
250 - Name of the control, a NUL-terminated ASCII string. This
251 information is intended for the user.
252
253 - .. row 4
254
255 - __s64
256
257 - ``minimum``
258
259 - Minimum value, inclusive. This field gives a lower bound for the
260 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
261 the minimum value is to be used for each possible control type.
262 Note that this a signed 64-bit value.
263
264 - .. row 5
265
266 - __s64
267
268 - ``maximum``
269
270 - Maximum value, inclusive. This field gives an upper bound for the
271 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
272 the maximum value is to be used for each possible control type.
273 Note that this a signed 64-bit value.
274
275 - .. row 6
276
277 - __u64
278
279 - ``step``
280
281 - This field gives a step size for the control. See enum
282 :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
283 to be used for each possible control type. Note that this an
284 unsigned 64-bit value.
285
286 Generally drivers should not scale hardware control values. It may
287 be necessary for example when the ``name`` or ``id`` imply a
288 particular unit and the hardware actually accepts only multiples
289 of said unit. If so, drivers must take care values are properly
290 rounded when scaling, such that errors will not accumulate on
291 repeated read-write cycles.
292
293 This field gives the smallest change of an integer control
294 actually affecting hardware. Often the information is needed when
295 the user can change controls by keyboard or GUI buttons, rather
296 than a slider. When for example a hardware register accepts values
297 0-511 and the driver reports 0-65535, step should be 128.
298
299 - .. row 7
300
301 - __s64
302
303 - ``default_value``
304
305 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
306 ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
307 or ``_U16`` control. Not valid for other types of controls.
308
309 .. note:: Drivers reset controls to their default value only when
310 the driver is first loaded, never afterwards.
311
312 - .. row 8
313
314 - __u32
315
316 - ``flags``
317
318 - Control flags, see :ref:`control-flags`.
319
320 - .. row 9
321
322 - __u32
323
324 - ``elem_size``
325
326 - The size in bytes of a single element of the array. Given a char
327 pointer ``p`` to a 3-dimensional array you can find the position
328 of cell ``(z, y, x)`` as follows:
329 ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
330 ``elem_size`` is always valid, also when the control isn't an
331 array. For string controls ``elem_size`` is equal to
332 ``maximum + 1``.
333
334 - .. row 10
335
336 - __u32
337
338 - ``elems``
339
340 - The number of elements in the N-dimensional array. If this control
341 is not an array, then ``elems`` is 1. The ``elems`` field can
342 never be 0.
343
344 - .. row 11
345
346 - __u32
347
348 - ``nr_of_dims``
349
350 - The number of dimension in the N-dimensional array. If this
351 control is not an array, then this field is 0.
352
353 - .. row 12
354
355 - __u32
356
357 - ``dims[V4L2_CTRL_MAX_DIMS]``
358
359 - The size of each dimension. The first ``nr_of_dims`` elements of
360 this array must be non-zero, all remaining elements must be zero.
361
362 - .. row 13
363
364 - __u32
365
366 - ``reserved``\ [32]
367
368 - Reserved for future extensions. Applications and drivers must set
369 the array to zero.
370
371
372
373.. _v4l2-querymenu:
374
375.. flat-table:: struct v4l2_querymenu
376 :header-rows: 0
377 :stub-columns: 0
378 :widths: 1 1 2 1
379
380
381 - .. row 1
382
383 - __u32
384
385 -
386 - ``id``
387
388 - Identifies the control, set by the application from the respective
389 struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
390
391 - .. row 2
392
393 - __u32
394
395 -
396 - ``index``
397
398 - Index of the menu item, starting at zero, set by the application.
399
400 - .. row 3
401
402 - union
403
404 -
405 -
406 -
407
408 - .. row 4
409
410 -
411 - __u8
412
413 - ``name``\ [32]
414
415 - Name of the menu item, a NUL-terminated ASCII string. This
416 information is intended for the user. This field is valid for
417 ``V4L2_CTRL_FLAG_MENU`` type controls.
418
419 - .. row 5
420
421 -
422 - __s64
423
424 - ``value``
425
426 - Value of the integer menu item. This field is valid for
427 ``V4L2_CTRL_FLAG_INTEGER_MENU`` type controls.
428
429 - .. row 6
430
431 - __u32
432
433 -
434 - ``reserved``
435
436 - Reserved for future extensions. Drivers must set the array to
437 zero.
438
439
440
441.. _v4l2-ctrl-type:
442
443.. flat-table:: enum v4l2_ctrl_type
444 :header-rows: 1
445 :stub-columns: 0
446 :widths: 30 5 5 5 55
447
448
449 - .. row 1
450
451 - Type
452
453 - ``minimum``
454
455 - ``step``
456
457 - ``maximum``
458
459 - Description
460
461 - .. row 2
462
463 - ``V4L2_CTRL_TYPE_INTEGER``
464
465 - any
466
467 - any
468
469 - any
470
471 - An integer-valued control ranging from minimum to maximum
472 inclusive. The step value indicates the increment between values.
473
474 - .. row 3
475
476 - ``V4L2_CTRL_TYPE_BOOLEAN``
477
478 - 0
479
480 - 1
481
482 - 1
483
484 - A boolean-valued control. Zero corresponds to "disabled", and one
485 means "enabled".
486
487 - .. row 4
488
489 - ``V4L2_CTRL_TYPE_MENU``
490
491 - ≥ 0
492
493 - 1
494
495 - N-1
496
497 - The control has a menu of N choices. The names of the menu items
498 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
499
500 - .. row 5
501
502 - ``V4L2_CTRL_TYPE_INTEGER_MENU``
503
504 - ≥ 0
505
506 - 1
507
508 - N-1
509
510 - The control has a menu of N choices. The values of the menu items
511 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
512 similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
513 the menu items are signed 64-bit integers.
514
515 - .. row 6
516
517 - ``V4L2_CTRL_TYPE_BITMASK``
518
519 - 0
520
521 - n/a
522
523 - any
524
525 - A bitmask field. The maximum value is the set of bits that can be
526 used, all other bits are to be 0. The maximum value is interpreted
527 as a __u32, allowing the use of bit 31 in the bitmask.
528
529 - .. row 7
530
531 - ``V4L2_CTRL_TYPE_BUTTON``
532
533 - 0
534
535 - 0
536
537 - 0
538
539 - A control which performs an action when set. Drivers must ignore
540 the value passed with ``VIDIOC_S_CTRL`` and return an ``EINVAL`` error
541 code on a ``VIDIOC_G_CTRL`` attempt.
542
543 - .. row 8
544
545 - ``V4L2_CTRL_TYPE_INTEGER64``
546
547 - any
548
549 - any
550
551 - any
552
553 - A 64-bit integer valued control. Minimum, maximum and step size
554 cannot be queried using ``VIDIOC_QUERYCTRL``. Only
555 ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
556 values, they should be interpreted as n/a when using
557 ``VIDIOC_QUERYCTRL``.
558
559 - .. row 9
560
561 - ``V4L2_CTRL_TYPE_STRING``
562
563 - ≥ 0
564
565 - ≥ 1
566
567 - ≥ 0
568
569 - The minimum and maximum string lengths. The step size means that
570 the string must be (minimum + N * step) characters long for N ≥ 0.
571 These lengths do not include the terminating zero, so in order to
572 pass a string of length 8 to
573 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
574 set the ``size`` field of struct
575 :ref:`v4l2_ext_control <v4l2-ext-control>` to 9. For
576 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
577 the ``size`` field to ``maximum`` + 1. Which character encoding is
578 used will depend on the string control itself and should be part
579 of the control documentation.
580
581 - .. row 10
582
583 - ``V4L2_CTRL_TYPE_CTRL_CLASS``
584
585 - n/a
586
587 - n/a
588
589 - n/a
590
591 - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
592 control ID equal to a control class code (see :ref:`ctrl-class`)
593 + 1, the ioctl returns the name of the control class and this
594 control type. Older drivers which do not support this feature
595 return an ``EINVAL`` error code.
596
597 - .. row 11
598
599 - ``V4L2_CTRL_TYPE_U8``
600
601 - any
602
603 - any
604
605 - any
606
607 - An unsigned 8-bit valued control ranging from minimum to maximum
608 inclusive. The step value indicates the increment between values.
609
610 - .. row 12
611
612 - ``V4L2_CTRL_TYPE_U16``
613
614 - any
615
616 - any
617
618 - any
619
620 - An unsigned 16-bit valued control ranging from minimum to maximum
621 inclusive. The step value indicates the increment between values.
622
623 - .. row 13
624
625 - ``V4L2_CTRL_TYPE_U32``
626
627 - any
628
629 - any
630
631 - any
632
633 - An unsigned 32-bit valued control ranging from minimum to maximum
634 inclusive. The step value indicates the increment between values.
635
636
637
638.. _control-flags:
639
640.. flat-table:: Control Flags
641 :header-rows: 0
642 :stub-columns: 0
643 :widths: 3 1 4
644
645
646 - .. row 1
647
648 - ``V4L2_CTRL_FLAG_DISABLED``
649
650 - 0x0001
651
652 - This control is permanently disabled and should be ignored by the
653 application. Any attempt to change the control will result in an
654 ``EINVAL`` error code.
655
656 - .. row 2
657
658 - ``V4L2_CTRL_FLAG_GRABBED``
659
660 - 0x0002
661
662 - This control is temporarily unchangeable, for example because
663 another application took over control of the respective resource.
664 Such controls may be displayed specially in a user interface.
665 Attempts to change the control may result in an ``EBUSY`` error code.
666
667 - .. row 3
668
669 - ``V4L2_CTRL_FLAG_READ_ONLY``
670
671 - 0x0004
672
673 - This control is permanently readable only. Any attempt to change
674 the control will result in an ``EINVAL`` error code.
675
676 - .. row 4
677
678 - ``V4L2_CTRL_FLAG_UPDATE``
679
680 - 0x0008
681
682 - A hint that changing this control may affect the value of other
683 controls within the same control class. Applications should update
684 their user interface accordingly.
685
686 - .. row 5
687
688 - ``V4L2_CTRL_FLAG_INACTIVE``
689
690 - 0x0010
691
692 - This control is not applicable to the current configuration and
693 should be displayed accordingly in a user interface. For example
694 the flag may be set on a MPEG audio level 2 bitrate control when
695 MPEG audio encoding level 1 was selected with another control.
696
697 - .. row 6
698
699 - ``V4L2_CTRL_FLAG_SLIDER``
700
701 - 0x0020
702
703 - A hint that this control is best represented as a slider-like
704 element in a user interface.
705
706 - .. row 7
707
708 - ``V4L2_CTRL_FLAG_WRITE_ONLY``
709
710 - 0x0040
711
712 - This control is permanently writable only. Any attempt to read the
713 control will result in an ``EACCES`` error code error code. This flag
714 is typically present for relative controls or action controls
715 where writing a value will cause the device to carry out a given
716 action (e. g. motor control) but no meaningful value can be
717 returned.
718
719 - .. row 8
720
721 - ``V4L2_CTRL_FLAG_VOLATILE``
722
723 - 0x0080
724
725 - This control is volatile, which means that the value of the
726 control changes continuously. A typical example would be the
727 current gain value if the device is in auto-gain mode. In such a
728 case the hardware calculates the gain value based on the lighting
729 conditions which can change over time.
730
731 .. note:: Setting a new value for a volatile control will have no
732 effect and no ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless
733 the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is
734 also set. Otherwise the new value will just be ignored.
735
736 - .. row 9
737
738 - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
739
740 - 0x0100
741
742 - This control has a pointer type, so its value has to be accessed
743 using one of the pointer fields of struct
744 :ref:`v4l2_ext_control <v4l2-ext-control>`. This flag is set
745 for controls that are an array, string, or have a compound type.
746 In all cases you have to set a pointer to memory containing the
747 payload of the control.
748
749 - .. row 10
750
751 - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
752
753 - 0x0200
754
755 - The value provided to the control will be propagated to the driver
756 even if it remains constant. This is required when the control
757 represents an action on the hardware. For example: clearing an
758 error flag or triggering the flash. All the controls of the type
759 ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
760
761
762Return Value
763============
764
765On success 0 is returned, on error -1 and the ``errno`` variable is set
766appropriately. The generic error codes are described at the
767:ref:`Generic Error Codes <gen-errors>` chapter.
768
769EINVAL
770 The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
771 invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
772 is invalid or ``index`` is out of range (less than ``minimum`` or
773 greater than ``maximum``) or this particular menu item is not
774 supported by the driver.
775
776EACCES
777 An attempt was made to read a write-only control.
778
779.. [#f1]
780 ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
781 can skip predefined controls not supported by the hardware (although
782 returning ``EINVAL`` would do as well), or disable predefined and private
783 controls after hardware detection without the trouble of reordering
784 control arrays and indices (``EINVAL`` cannot be used to skip private
785 controls because it would prematurely end the enumeration).