Merge tag 'pinctrl-v4.21-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw...
[muen/linux.git] / Documentation / media / uapi / v4l / vidioc-queryctrl.rst
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.
7 ..
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10 .. _VIDIOC_QUERYCTRL:
11
12 *******************************************************************
13 ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
14 *******************************************************************
15
16 Name
17 ====
18
19 VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
20
21
22 Synopsis
23 ========
24
25 .. c:function:: int ioctl( int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp )
26     :name: VIDIOC_QUERYCTRL
27
28 .. c:function:: int ioctl( int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp )
29     :name: VIDIOC_QUERY_EXT_CTRL
30
31 .. c:function:: int ioctl( int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp )
32     :name: VIDIOC_QUERYMENU
33
34
35 Arguments
36 =========
37
38 ``fd``
39     File descriptor returned by :ref:`open() <func-open>`.
40
41 ``argp``
42     Pointer to struct :c:type:`v4l2_queryctl`, :c:type:`v4l2_query_ext_ctrl`
43     or :c:type`v4l2_querymenu` (depending on the ioctl).
44
45
46 Description
47 ===========
48
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
53 ``id`` is invalid.
54
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
61 returns ``EINVAL``.
62
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]_
66
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``.
76
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.
81
82 ``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
83 ``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
84 as well.
85
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``,
94 inclusive.
95
96 .. note::
97
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.
102
103 See also the examples in :ref:`control`.
104
105
106 .. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}|
107
108 .. _v4l2-queryctrl:
109
110 .. cssclass:: longtable
111
112 .. flat-table:: struct v4l2_queryctrl
113     :header-rows:  0
114     :stub-columns: 0
115     :widths:       1 1 2
116
117     * - __u32
118       - ``id``
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.
124     * - __u32
125       - ``type``
126       - Type of control, see :c:type:`v4l2_ctrl_type`.
127     * - __u8
128       - ``name``\ [32]
129       - Name of the control, a NUL-terminated ASCII string. This
130         information is intended for the user.
131     * - __s32
132       - ``minimum``
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.
137     * - __s32
138       - ``maximum``
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.
143     * - __s32
144       - ``step``
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.
149
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.
156
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.
162
163         Note that although signed, the step value is supposed to be always
164         positive.
165     * - __s32
166       - ``default_value``
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.
170
171         .. note::
172
173            Drivers reset controls to their default value only when
174            the driver is first loaded, never afterwards.
175     * - __u32
176       - ``flags``
177       - Control flags, see :ref:`control-flags`.
178     * - __u32
179       - ``reserved``\ [2]
180       - Reserved for future extensions. Drivers must set the array to
181         zero.
182
183
184
185 .. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}|
186
187 .. _v4l2-query-ext-ctrl:
188
189 .. cssclass:: longtable
190
191 .. flat-table:: struct v4l2_query_ext_ctrl
192     :header-rows:  0
193     :stub-columns: 0
194     :widths:       1 1 2
195
196     * - __u32
197       - ``id``
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
205         ID.
206     * - __u32
207       - ``type``
208       - Type of control, see :c:type:`v4l2_ctrl_type`.
209     * - char
210       - ``name``\ [32]
211       - Name of the control, a NUL-terminated ASCII string. This
212         information is intended for the user.
213     * - __s64
214       - ``minimum``
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.
219     * - __s64
220       - ``maximum``
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.
225     * - __u64
226       - ``step``
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.
231
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.
238
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.
244     * - __s64
245       - ``default_value``
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.
249
250         .. note::
251
252            Drivers reset controls to their default value only when
253            the driver is first loaded, never afterwards.
254     * - __u32
255       - ``flags``
256       - Control flags, see :ref:`control-flags`.
257     * - __u32
258       - ``elem_size``
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
265         ``maximum + 1``.
266     * - __u32
267       - ``elems``
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
270         never be 0.
271     * - __u32
272       - ``nr_of_dims``
273       - The number of dimension in the N-dimensional array. If this
274         control is not an array, then this field is 0.
275     * - __u32
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.
279     * - __u32
280       - ``reserved``\ [32]
281       - Reserved for future extensions. Applications and drivers must set
282         the array to zero.
283
284
285
286 .. tabularcolumns:: |p{1.2cm}|p{1.0cm}|p{1.7cm}|p{13.0cm}|
287
288 .. _v4l2-querymenu:
289
290 .. flat-table:: struct v4l2_querymenu
291     :header-rows:  0
292     :stub-columns: 0
293     :widths:       1 1 2 1
294
295     * - __u32
296       -
297       - ``id``
298       - Identifies the control, set by the application from the respective
299         struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
300     * - __u32
301       -
302       - ``index``
303       - Index of the menu item, starting at zero, set by the application.
304     * - union
305       -
306       -
307       -
308     * -
309       - __u8
310       - ``name``\ [32]
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.
314     * -
315       - __s64
316       - ``value``
317       - Value of the integer menu item. This field is valid for
318         ``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls.
319     * - __u32
320       -
321       - ``reserved``
322       - Reserved for future extensions. Drivers must set the array to
323         zero.
324
325
326
327 .. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}|
328
329 .. c:type:: v4l2_ctrl_type
330
331 .. cssclass:: longtable
332
333 .. flat-table:: enum v4l2_ctrl_type
334     :header-rows:  1
335     :stub-columns: 0
336     :widths:       30 5 5 5 55
337
338     * - Type
339       - ``minimum``
340       - ``step``
341       - ``maximum``
342       - Description
343     * - ``V4L2_CTRL_TYPE_INTEGER``
344       - any
345       - any
346       - any
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``
350       - 0
351       - 1
352       - 1
353       - A boolean-valued control. Zero corresponds to "disabled", and one
354         means "enabled".
355     * - ``V4L2_CTRL_TYPE_MENU``
356       - ≥ 0
357       - 1
358       - N-1
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``
362       - ≥ 0
363       - 1
364       - N-1
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``
370       - 0
371       - n/a
372       - any
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``
377       - 0
378       - 0
379       - 0
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``
384       - any
385       - any
386       - any
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``
393       - ≥ 0
394       - ≥ 1
395       - ≥ 0
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``
408       - n/a
409       - n/a
410       - n/a
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``
417       - any
418       - any
419       - any
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``
423       - any
424       - any
425       - any
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``
429       - any
430       - any
431       - any
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``
435       - n/a
436       - n/a
437       - n/a
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``
441       - n/a
442       - n/a
443       - n/a
444       - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2
445         quantization matrices for stateless video decoders.
446
447 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
448
449 .. _control-flags:
450
451 .. cssclass:: longtable
452
453 .. flat-table:: Control Flags
454     :header-rows:  0
455     :stub-columns: 0
456     :widths:       3 1 4
457
458     * - ``V4L2_CTRL_FLAG_DISABLED``
459       - 0x0001
460       - This control is permanently disabled and should be ignored by the
461         application. Any attempt to change the control will result in an
462         ``EINVAL`` error code.
463     * - ``V4L2_CTRL_FLAG_GRABBED``
464       - 0x0002
465       - This control is temporarily unchangeable, for example because
466         another application took over control of the respective resource.
467         Such controls may be displayed specially in a user interface.
468         Attempts to change the control may result in an ``EBUSY`` error code.
469     * - ``V4L2_CTRL_FLAG_READ_ONLY``
470       - 0x0004
471       - This control is permanently readable only. Any attempt to change
472         the control will result in an ``EINVAL`` error code.
473     * - ``V4L2_CTRL_FLAG_UPDATE``
474       - 0x0008
475       - A hint that changing this control may affect the value of other
476         controls within the same control class. Applications should update
477         their user interface accordingly.
478     * - ``V4L2_CTRL_FLAG_INACTIVE``
479       - 0x0010
480       - This control is not applicable to the current configuration and
481         should be displayed accordingly in a user interface. For example
482         the flag may be set on a MPEG audio level 2 bitrate control when
483         MPEG audio encoding level 1 was selected with another control.
484     * - ``V4L2_CTRL_FLAG_SLIDER``
485       - 0x0020
486       - A hint that this control is best represented as a slider-like
487         element in a user interface.
488     * - ``V4L2_CTRL_FLAG_WRITE_ONLY``
489       - 0x0040
490       - This control is permanently writable only. Any attempt to read the
491         control will result in an ``EACCES`` error code error code. This flag
492         is typically present for relative controls or action controls
493         where writing a value will cause the device to carry out a given
494         action (e. g. motor control) but no meaningful value can be
495         returned.
496     * - ``V4L2_CTRL_FLAG_VOLATILE``
497       - 0x0080
498       - This control is volatile, which means that the value of the
499         control changes continuously. A typical example would be the
500         current gain value if the device is in auto-gain mode. In such a
501         case the hardware calculates the gain value based on the lighting
502         conditions which can change over time.
503
504         .. note::
505
506            Setting a new value for a volatile control will be ignored
507            unless
508            :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>`
509            is also set.
510            Setting a new value for a volatile control will *never* trigger a
511            :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event.
512     * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
513       - 0x0100
514       - This control has a pointer type, so its value has to be accessed
515         using one of the pointer fields of struct
516         :c:type:`v4l2_ext_control`. This flag is set
517         for controls that are an array, string, or have a compound type.
518         In all cases you have to set a pointer to memory containing the
519         payload of the control.
520     * .. _FLAG_EXECUTE_ON_WRITE:
521
522       - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
523       - 0x0200
524       - The value provided to the control will be propagated to the driver
525         even if it remains constant. This is required when the control
526         represents an action on the hardware. For example: clearing an
527         error flag or triggering the flash. All the controls of the type
528         ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
529     * .. _FLAG_MODIFY_LAYOUT:
530
531       - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT``
532       - 0x0400
533       - Changing this control value may modify the layout of the
534         buffer (for video devices) or the media bus format (for sub-devices).
535
536         A typical example would be the ``V4L2_CID_ROTATE`` control.
537
538         Note that typically controls with this flag will also set the
539         ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or
540         streaming is in progress since most drivers do not support changing
541         the format in that case.
542
543
544 Return Value
545 ============
546
547 On success 0 is returned, on error -1 and the ``errno`` variable is set
548 appropriately. The generic error codes are described at the
549 :ref:`Generic Error Codes <gen-errors>` chapter.
550
551 EINVAL
552     The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
553     invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
554     is invalid or ``index`` is out of range (less than ``minimum`` or
555     greater than ``maximum``) or this particular menu item is not
556     supported by the driver.
557
558 EACCES
559     An attempt was made to read a write-only control.
560
561 .. [#f1]
562    ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
563    can skip predefined controls not supported by the hardware (although
564    returning ``EINVAL`` would do as well), or disable predefined and private
565    controls after hardware detection without the trouble of reordering
566    control arrays and indices (``EINVAL`` cannot be used to skip private
567    controls because it would prematurely end the enumeration).