1 .. Permission is granted to copy, distribute and/or modify this
2 .. document under the terms of the GNU Free Documentation License,
3 .. Version 1.1 or any later version published by the Free Software
4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
5 .. and no Back-Cover Texts. A copy of the license is included at
6 .. Documentation/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
12 *******************************************************************
13 ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
14 *******************************************************************
19 VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
25 .. c:function:: int ioctl( int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp )
26 :name: VIDIOC_QUERYCTRL
28 .. c:function:: int ioctl( int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp )
29 :name: VIDIOC_QUERY_EXT_CTRL
31 .. c:function:: int ioctl( int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp )
32 :name: VIDIOC_QUERYMENU
39 File descriptor returned by :ref:`open() <func-open>`.
42 Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl`
43 or :c:type:`v4l2_querymenu` (depending on the ioctl).
49 To query the attributes of a control applications set the ``id`` field
50 of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
51 ``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
52 fills the rest of the structure or returns an ``EINVAL`` error code when the
55 It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
56 with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
57 exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
58 this range is not supported. Further applications can enumerate private
59 controls, which are not defined in this specification, by starting at
60 ``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
63 In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
64 in the ``flags`` field this control is permanently disabled and should
65 be ignored by the application. [#f1]_
67 When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
68 driver returns the next supported non-compound control, or ``EINVAL`` if
69 there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
70 can be specified to enumerate all compound controls (i.e. controls with
71 type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
72 controls that contain more than one value). Specify both
73 ``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
74 order to enumerate all controls, compound or not. Drivers which do not
75 support these flags yet always return ``EINVAL``.
77 The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
78 support controls that can use compound types, and to expose additional
79 control information that cannot be returned in struct
80 :ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
82 ``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
83 ``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
86 Additional information is required for menu controls: the names of the
87 menu items. To query them applications set the ``id`` and ``index``
88 fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
89 ``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
90 fills the rest of the structure or returns an ``EINVAL`` error code when the
91 ``id`` or ``index`` is invalid. Menu items are enumerated by calling
92 ``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
93 :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
98 It is possible for ``VIDIOC_QUERYMENU`` to return
99 an ``EINVAL`` error code for some indices between ``minimum`` and
100 ``maximum``. In that case that particular menu item is not supported by
101 this driver. Also note that the ``minimum`` value is not necessarily 0.
103 See also the examples in :ref:`control`.
106 .. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}|
110 .. cssclass:: longtable
112 .. flat-table:: struct v4l2_queryctrl
119 - Identifies the control, set by the application. See
120 :ref:`control-id` for predefined IDs. When the ID is ORed with
121 V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
122 returns the first control with a higher ID. Drivers which do not
123 support this flag yet always return an ``EINVAL`` error code.
126 - Type of control, see :c:type:`v4l2_ctrl_type`.
129 - Name of the control, a NUL-terminated ASCII string. This
130 information is intended for the user.
133 - Minimum value, inclusive. This field gives a lower bound for the
134 control. See enum :c:type:`v4l2_ctrl_type` how
135 the minimum value is to be used for each possible control type.
136 Note that this a signed 32-bit value.
139 - Maximum value, inclusive. This field gives an upper bound for the
140 control. See enum :c:type:`v4l2_ctrl_type` how
141 the maximum value is to be used for each possible control type.
142 Note that this a signed 32-bit value.
145 - This field gives a step size for the control. See enum
146 :c:type:`v4l2_ctrl_type` how the step value is
147 to be used for each possible control type. Note that this an
148 unsigned 32-bit value.
150 Generally drivers should not scale hardware control values. It may
151 be necessary for example when the ``name`` or ``id`` imply a
152 particular unit and the hardware actually accepts only multiples
153 of said unit. If so, drivers must take care values are properly
154 rounded when scaling, such that errors will not accumulate on
155 repeated read-write cycles.
157 This field gives the smallest change of an integer control
158 actually affecting hardware. Often the information is needed when
159 the user can change controls by keyboard or GUI buttons, rather
160 than a slider. When for example a hardware register accepts values
161 0-511 and the driver reports 0-65535, step should be 128.
163 Note that although signed, the step value is supposed to be always
167 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
168 ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
169 for other types of controls.
173 Drivers reset controls to their default value only when
174 the driver is first loaded, never afterwards.
177 - Control flags, see :ref:`control-flags`.
180 - Reserved for future extensions. Drivers must set the array to
185 .. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}|
187 .. _v4l2-query-ext-ctrl:
189 .. cssclass:: longtable
191 .. flat-table:: struct v4l2_query_ext_ctrl
198 - Identifies the control, set by the application. See
199 :ref:`control-id` for predefined IDs. When the ID is ORed with
200 ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
201 returns the first non-compound control with a higher ID. When the
202 ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
203 the flag and returns the first compound control with a higher ID.
204 Set both to get the first control (compound or not) with a higher
208 - Type of control, see :c:type:`v4l2_ctrl_type`.
211 - Name of the control, a NUL-terminated ASCII string. This
212 information is intended for the user.
215 - Minimum value, inclusive. This field gives a lower bound for the
216 control. See enum :c:type:`v4l2_ctrl_type` how
217 the minimum value is to be used for each possible control type.
218 Note that this a signed 64-bit value.
221 - Maximum value, inclusive. This field gives an upper bound for the
222 control. See enum :c:type:`v4l2_ctrl_type` how
223 the maximum value is to be used for each possible control type.
224 Note that this a signed 64-bit value.
227 - This field gives a step size for the control. See enum
228 :c:type:`v4l2_ctrl_type` how the step value is
229 to be used for each possible control type. Note that this an
230 unsigned 64-bit value.
232 Generally drivers should not scale hardware control values. It may
233 be necessary for example when the ``name`` or ``id`` imply a
234 particular unit and the hardware actually accepts only multiples
235 of said unit. If so, drivers must take care values are properly
236 rounded when scaling, such that errors will not accumulate on
237 repeated read-write cycles.
239 This field gives the smallest change of an integer control
240 actually affecting hardware. Often the information is needed when
241 the user can change controls by keyboard or GUI buttons, rather
242 than a slider. When for example a hardware register accepts values
243 0-511 and the driver reports 0-65535, step should be 128.
246 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
247 ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
248 or ``_U16`` control. Not valid for other types of controls.
252 Drivers reset controls to their default value only when
253 the driver is first loaded, never afterwards.
256 - Control flags, see :ref:`control-flags`.
259 - The size in bytes of a single element of the array. Given a char
260 pointer ``p`` to a 3-dimensional array you can find the position
261 of cell ``(z, y, x)`` as follows:
262 ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
263 ``elem_size`` is always valid, also when the control isn't an
264 array. For string controls ``elem_size`` is equal to
268 - The number of elements in the N-dimensional array. If this control
269 is not an array, then ``elems`` is 1. The ``elems`` field can
273 - The number of dimension in the N-dimensional array. If this
274 control is not an array, then this field is 0.
276 - ``dims[V4L2_CTRL_MAX_DIMS]``
277 - The size of each dimension. The first ``nr_of_dims`` elements of
278 this array must be non-zero, all remaining elements must be zero.
281 - Reserved for future extensions. Applications and drivers must set
286 .. tabularcolumns:: |p{1.2cm}|p{1.0cm}|p{1.7cm}|p{13.0cm}|
290 .. flat-table:: struct v4l2_querymenu
298 - Identifies the control, set by the application from the respective
299 struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
303 - Index of the menu item, starting at zero, set by the application.
311 - Name of the menu item, a NUL-terminated ASCII string. This
312 information is intended for the user. This field is valid for
313 ``V4L2_CTRL_TYPE_MENU`` type controls.
317 - Value of the integer menu item. This field is valid for
318 ``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls.
322 - Reserved for future extensions. Drivers must set the array to
327 .. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}|
329 .. c:type:: v4l2_ctrl_type
331 .. cssclass:: longtable
333 .. flat-table:: enum v4l2_ctrl_type
343 * - ``V4L2_CTRL_TYPE_INTEGER``
347 - An integer-valued control ranging from minimum to maximum
348 inclusive. The step value indicates the increment between values.
349 * - ``V4L2_CTRL_TYPE_BOOLEAN``
353 - A boolean-valued control. Zero corresponds to "disabled", and one
355 * - ``V4L2_CTRL_TYPE_MENU``
359 - The control has a menu of N choices. The names of the menu items
360 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
361 * - ``V4L2_CTRL_TYPE_INTEGER_MENU``
365 - The control has a menu of N choices. The values of the menu items
366 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
367 similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
368 the menu items are signed 64-bit integers.
369 * - ``V4L2_CTRL_TYPE_BITMASK``
373 - A bitmask field. The maximum value is the set of bits that can be
374 used, all other bits are to be 0. The maximum value is interpreted
375 as a __u32, allowing the use of bit 31 in the bitmask.
376 * - ``V4L2_CTRL_TYPE_BUTTON``
380 - A control which performs an action when set. Drivers must ignore
381 the value passed with ``VIDIOC_S_CTRL`` and return an ``EINVAL`` error
382 code on a ``VIDIOC_G_CTRL`` attempt.
383 * - ``V4L2_CTRL_TYPE_INTEGER64``
387 - A 64-bit integer valued control. Minimum, maximum and step size
388 cannot be queried using ``VIDIOC_QUERYCTRL``. Only
389 ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
390 values, they should be interpreted as n/a when using
391 ``VIDIOC_QUERYCTRL``.
392 * - ``V4L2_CTRL_TYPE_STRING``
396 - The minimum and maximum string lengths. The step size means that
397 the string must be (minimum + N * step) characters long for N ≥ 0.
398 These lengths do not include the terminating zero, so in order to
399 pass a string of length 8 to
400 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
401 set the ``size`` field of struct
402 :c:type:`v4l2_ext_control` to 9. For
403 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
404 the ``size`` field to ``maximum`` + 1. Which character encoding is
405 used will depend on the string control itself and should be part
406 of the control documentation.
407 * - ``V4L2_CTRL_TYPE_CTRL_CLASS``
411 - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
412 control ID equal to a control class code (see :ref:`ctrl-class`)
413 + 1, the ioctl returns the name of the control class and this
414 control type. Older drivers which do not support this feature
415 return an ``EINVAL`` error code.
416 * - ``V4L2_CTRL_TYPE_U8``
420 - An unsigned 8-bit valued control ranging from minimum to maximum
421 inclusive. The step value indicates the increment between values.
422 * - ``V4L2_CTRL_TYPE_U16``
426 - An unsigned 16-bit valued control ranging from minimum to maximum
427 inclusive. The step value indicates the increment between values.
428 * - ``V4L2_CTRL_TYPE_U32``
432 - An unsigned 32-bit valued control ranging from minimum to maximum
433 inclusive. The step value indicates the increment between values.
434 * - ``V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS``
438 - A struct :c:type:`v4l2_ctrl_mpeg2_slice_params`, containing MPEG-2
439 slice parameters for stateless video decoders.
440 * - ``V4L2_CTRL_TYPE_MPEG2_QUANTIZATION``
444 - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2
445 quantization matrices for stateless video decoders.
446 * - ``V4L2_CTRL_TYPE_H264_SPS``
450 - A struct :c:type:`v4l2_ctrl_h264_sps`, containing H264
451 sequence parameters for stateless video decoders.
452 * - ``V4L2_CTRL_TYPE_H264_PPS``
456 - A struct :c:type:`v4l2_ctrl_h264_pps`, containing H264
457 picture parameters for stateless video decoders.
458 * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``
462 - A struct :c:type:`v4l2_ctrl_h264_scaling_matrix`, containing H264
463 scaling matrices for stateless video decoders.
464 * - ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``
468 - A struct :c:type:`v4l2_ctrl_h264_slice_params`, containing H264
469 slice parameters for stateless video decoders.
470 * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``
474 - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264
475 decode parameters for stateless video decoders.
477 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
481 .. cssclass:: longtable
483 .. flat-table:: Control Flags
488 * - ``V4L2_CTRL_FLAG_DISABLED``
490 - This control is permanently disabled and should be ignored by the
491 application. Any attempt to change the control will result in an
492 ``EINVAL`` error code.
493 * - ``V4L2_CTRL_FLAG_GRABBED``
495 - This control is temporarily unchangeable, for example because
496 another application took over control of the respective resource.
497 Such controls may be displayed specially in a user interface.
498 Attempts to change the control may result in an ``EBUSY`` error code.
499 * - ``V4L2_CTRL_FLAG_READ_ONLY``
501 - This control is permanently readable only. Any attempt to change
502 the control will result in an ``EINVAL`` error code.
503 * - ``V4L2_CTRL_FLAG_UPDATE``
505 - A hint that changing this control may affect the value of other
506 controls within the same control class. Applications should update
507 their user interface accordingly.
508 * - ``V4L2_CTRL_FLAG_INACTIVE``
510 - This control is not applicable to the current configuration and
511 should be displayed accordingly in a user interface. For example
512 the flag may be set on a MPEG audio level 2 bitrate control when
513 MPEG audio encoding level 1 was selected with another control.
514 * - ``V4L2_CTRL_FLAG_SLIDER``
516 - A hint that this control is best represented as a slider-like
517 element in a user interface.
518 * - ``V4L2_CTRL_FLAG_WRITE_ONLY``
520 - This control is permanently writable only. Any attempt to read the
521 control will result in an ``EACCES`` error code error code. This flag
522 is typically present for relative controls or action controls
523 where writing a value will cause the device to carry out a given
524 action (e. g. motor control) but no meaningful value can be
526 * - ``V4L2_CTRL_FLAG_VOLATILE``
528 - This control is volatile, which means that the value of the
529 control changes continuously. A typical example would be the
530 current gain value if the device is in auto-gain mode. In such a
531 case the hardware calculates the gain value based on the lighting
532 conditions which can change over time.
536 Setting a new value for a volatile control will be ignored
538 :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>`
540 Setting a new value for a volatile control will *never* trigger a
541 :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event.
542 * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
544 - This control has a pointer type, so its value has to be accessed
545 using one of the pointer fields of struct
546 :c:type:`v4l2_ext_control`. This flag is set
547 for controls that are an array, string, or have a compound type.
548 In all cases you have to set a pointer to memory containing the
549 payload of the control.
550 * .. _FLAG_EXECUTE_ON_WRITE:
552 - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
554 - The value provided to the control will be propagated to the driver
555 even if it remains constant. This is required when the control
556 represents an action on the hardware. For example: clearing an
557 error flag or triggering the flash. All the controls of the type
558 ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
559 * .. _FLAG_MODIFY_LAYOUT:
561 - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT``
563 - Changing this control value may modify the layout of the
564 buffer (for video devices) or the media bus format (for sub-devices).
566 A typical example would be the ``V4L2_CID_ROTATE`` control.
568 Note that typically controls with this flag will also set the
569 ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or
570 streaming is in progress since most drivers do not support changing
571 the format in that case.
577 On success 0 is returned, on error -1 and the ``errno`` variable is set
578 appropriately. The generic error codes are described at the
579 :ref:`Generic Error Codes <gen-errors>` chapter.
582 The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
583 invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
584 is invalid or ``index`` is out of range (less than ``minimum`` or
585 greater than ``maximum``) or this particular menu item is not
586 supported by the driver.
589 An attempt was made to read a write-only control.
592 ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
593 can skip predefined controls not supported by the hardware (although
594 returning ``EINVAL`` would do as well), or disable predefined and private
595 controls after hardware detection without the trouble of reordering
596 control arrays and indices (``EINVAL`` cannot be used to skip private
597 controls because it would prematurely end the enumeration).