1 .. SPDX-License-Identifier: GPL-2.0
2
3 V4L2 Controls
4 =============
5
6 Introduction
7 ------------
8
9 The V4L2 control API seems simple enough, but
10 implement correctly in drivers. But much of th
11 is actually not driver specific and can be mov
12
13 After all, the only part that a driver develop
14
15 1) How do I add a control?
16 2) How do I set the control's value? (i.e. s_c
17
18 And occasionally:
19
20 3) How do I get the control's value? (i.e. g_v
21 4) How do I validate the user's proposed contr
22
23 All the rest is something that can be done cen
24
25 The control framework was created in order to
26 V4L2 specification with respect to controls in
27 life as easy as possible for the driver develo
28
29 Note that the control framework relies on the
30 :c:type:`v4l2_device` for V4L2 drivers and str
31 sub-device drivers.
32
33
34 Objects in the framework
35 ------------------------
36
37 There are two main objects:
38
39 The :c:type:`v4l2_ctrl` object describes the c
40 track of the control's value (both the current
41 value).
42
43 :c:type:`v4l2_ctrl_handler` is the object that
44 maintains a list of v4l2_ctrl objects that it
45 references to controls, possibly to controls o
46
47
48 Basic usage for V4L2 and sub-device drivers
49 -------------------------------------------
50
51 1) Prepare the driver:
52
53 .. code-block:: c
54
55 #include <media/v4l2-ctrls.h>
56
57 1.1) Add the handler to your driver's top-leve
58
59 For V4L2 drivers:
60
61 .. code-block:: c
62
63 struct foo_dev {
64 ...
65 struct v4l2_device v4l2_dev;
66 ...
67 struct v4l2_ctrl_handler ctrl_
68 ...
69 };
70
71 For sub-device drivers:
72
73 .. code-block:: c
74
75 struct foo_dev {
76 ...
77 struct v4l2_subdev sd;
78 ...
79 struct v4l2_ctrl_handler ctrl_
80 ...
81 };
82
83 1.2) Initialize the handler:
84
85 .. code-block:: c
86
87 v4l2_ctrl_handler_init(&foo->ctrl_hand
88
89 The second argument is a hint telling the func
90 handler is expected to handle. It will allocat
91 information. It is a hint only.
92
93 1.3) Hook the control handler into the driver:
94
95 For V4L2 drivers:
96
97 .. code-block:: c
98
99 foo->v4l2_dev.ctrl_handler = &foo->ctr
100
101 For sub-device drivers:
102
103 .. code-block:: c
104
105 foo->sd.ctrl_handler = &foo->ctrl_hand
106
107 1.4) Clean up the handler at the end:
108
109 .. code-block:: c
110
111 v4l2_ctrl_handler_free(&foo->ctrl_hand
112
113
114 2) Add controls:
115
116 You add non-menu controls by calling :c:func:`
117
118 .. code-block:: c
119
120 struct v4l2_ctrl *v4l2_ctrl_new_std(st
121 const struct v4l2_ctrl
122 u32 id, s32 min, s32 m
123
124 Menu and integer menu controls are added by ca
125 :c:func:`v4l2_ctrl_new_std_menu`:
126
127 .. code-block:: c
128
129 struct v4l2_ctrl *v4l2_ctrl_new_std_me
130 const struct v4l2_ctrl
131 u32 id, s32 max, s32 s
132
133 Menu controls with a driver specific menu are
134 :c:func:`v4l2_ctrl_new_std_menu_items`:
135
136 .. code-block:: c
137
138 struct v4l2_ctrl *v4l2_ctrl_new_std_men
139 struct v4l2_ctrl_handle
140 const struct v4l2_ctrl_
141 s32 skip_mask, s32 def,
142
143 Standard compound controls can be added by cal
144 :c:func:`v4l2_ctrl_new_std_compound`:
145
146 .. code-block:: c
147
148 struct v4l2_ctrl *v4l2_ctrl_new_std_com
149 const struct v4l2_ctrl_
150 const union v4l2_ctrl_p
151
152 Integer menu controls with a driver specific m
153 :c:func:`v4l2_ctrl_new_int_menu`:
154
155 .. code-block:: c
156
157 struct v4l2_ctrl *v4l2_ctrl_new_int_me
158 const struct v4l2_ctrl
159 u32 id, s32 max, s32 d
160
161 These functions are typically called right aft
162 :c:func:`v4l2_ctrl_handler_init`:
163
164 .. code-block:: c
165
166 static const s64 exp_bias_qmenu[] = {
167 -2, -1, 0, 1, 2
168 };
169 static const char * const test_pattern
170 "Disabled",
171 "Vertical Bars",
172 "Solid Black",
173 "Solid White",
174 };
175
176 v4l2_ctrl_handler_init(&foo->ctrl_hand
177 v4l2_ctrl_new_std(&foo->ctrl_handler,
178 V4L2_CID_BRIGHTNESS, 0
179 v4l2_ctrl_new_std(&foo->ctrl_handler,
180 V4L2_CID_CONTRAST, 0,
181 v4l2_ctrl_new_std_menu(&foo->ctrl_hand
182 V4L2_CID_POWER_LINE_FR
183 V4L2_CID_POWER_LINE_FR
184 V4L2_CID_POWER_LINE_FR
185 v4l2_ctrl_new_int_menu(&foo->ctrl_hand
186 V4L2_CID_EXPOSURE_BIAS
187 ARRAY_SIZE(exp_bias_qm
188 ARRAY_SIZE(exp_bias_qm
189 exp_bias_qmenu);
190 v4l2_ctrl_new_std_menu_items(&foo->ctr
191 V4L2_CID_TEST_PATTERN,
192 0, test_pattern);
193 ...
194 if (foo->ctrl_handler.error) {
195 int err = foo->ctrl_handler.er
196
197 v4l2_ctrl_handler_free(&foo->c
198 return err;
199 }
200
201 The :c:func:`v4l2_ctrl_new_std` function retur
202 the new control, but if you do not need to acc
203 control ops, then there is no need to store it
204
205 The :c:func:`v4l2_ctrl_new_std` function will
206 the control ID except for the min, max, step a
207 passed in the last four arguments. These value
208 control attributes like type, name, flags are
209 current value will be set to the default value
210
211 The :c:func:`v4l2_ctrl_new_std_menu` function
212 used for menu controls. There is no min argume
213 menu controls, and instead of a step there is
214 X is 1, then menu item X is skipped.
215
216 The :c:func:`v4l2_ctrl_new_int_menu` function
217 integer menu control with driver-specific item
218 from v4l2_ctrl_new_std_menu in that it doesn't
219 takes as the last argument an array of signed
220 exact menu item list.
221
222 The :c:func:`v4l2_ctrl_new_std_menu_items` fun
223 v4l2_ctrl_new_std_menu but takes an extra para
224 driver specific menu for an otherwise standard
225 for this control is the test pattern control f
226 devices that have the capability to generate t
227 patterns are hardware specific, so the content
228 device to device.
229
230 Note that if something fails, the function wil
231 set ctrl_handler->error to the error code. If
232 set, then it will just return and do nothing.
233 v4l2_ctrl_handler_init if it cannot allocate t
234
235 This makes it easy to init the handler and jus
236 the error code at the end. Saves a lot of repe
237
238 It is recommended to add controls in ascending
239 a bit faster that way.
240
241 3) Optionally force initial control setup:
242
243 .. code-block:: c
244
245 v4l2_ctrl_handler_setup(&foo->ctrl_han
246
247 This will call s_ctrl for all controls uncondi
248 initializes the hardware to the default contro
249 that you do this as this ensures that both the
250 the hardware are in sync.
251
252 4) Finally: implement the :c:type:`v4l2_ctrl_o
253
254 .. code-block:: c
255
256 static const struct v4l2_ctrl_ops foo_
257 .s_ctrl = foo_s_ctrl,
258 };
259
260 Usually all you need is s_ctrl:
261
262 .. code-block:: c
263
264 static int foo_s_ctrl(struct v4l2_ctrl
265 {
266 struct foo *state = container_
267
268 switch (ctrl->id) {
269 case V4L2_CID_BRIGHTNESS:
270 write_reg(0x123, ctrl-
271 break;
272 case V4L2_CID_CONTRAST:
273 write_reg(0x456, ctrl-
274 break;
275 }
276 return 0;
277 }
278
279 The control ops are called with the v4l2_ctrl
280 The new control value has already been validat
281 to actually update the hardware registers.
282
283 You're done! And this is sufficient for most o
284 to do any validation of control values, or imp
285 and QUERYMENU. And G/S_CTRL as well as G/TRY/S
286
287
288 .. note::
289
290 The remainder sections deal with more advan
291 In practice the basic usage as described ab
292
293
294 Inheriting Sub-device Controls
295 ------------------------------
296
297 When a sub-device is registered with a V4L2 dr
298 v4l2_device_register_subdev() and the ctrl_han
299 and v4l2_device are set, then the controls of
300 automatically available in the V4L2 driver as
301 contains controls that already exist in the V4
302 skipped (so a V4L2 driver can always override
303
304 What happens here is that v4l2_device_register
305 v4l2_ctrl_add_handler() adding the controls of
306 of v4l2_device.
307
308
309 Accessing Control Values
310 ------------------------
311
312 The following union is used inside the control
313 values:
314
315 .. code-block:: c
316
317 union v4l2_ctrl_ptr {
318 s32 *p_s32;
319 s64 *p_s64;
320 char *p_char;
321 void *p;
322 };
323
324 The v4l2_ctrl struct contains these fields tha
325 current and new values:
326
327 .. code-block:: c
328
329 s32 val;
330 struct {
331 s32 val;
332 } cur;
333
334
335 union v4l2_ctrl_ptr p_new;
336 union v4l2_ctrl_ptr p_cur;
337
338 If the control has a simple s32 type, then:
339
340 .. code-block:: c
341
342 &ctrl->val == ctrl->p_new.p_s32
343 &ctrl->cur.val == ctrl->p_cur.p_s32
344
345 For all other types use ctrl->p_cur.p<somethin
346 and cur.val fields can be considered an alias
347
348 Within the control ops you can freely use thes
349 themselves. The p_char pointers point to chara
350 ctrl->maximum + 1, and are always 0-terminated
351
352 Unless the control is marked volatile the p_cu
353 current cached control value. When you create
354 identical to the default value. After calling
355 value is passed to the hardware. It is general
356 function.
357
358 Whenever a new value is set that new value is
359 that most drivers do not need to implement the
360 exception is for controls that return a volati
361 strength read-out that changes continuously. I
362 implement g_volatile_ctrl like this:
363
364 .. code-block:: c
365
366 static int foo_g_volatile_ctrl(struct
367 {
368 switch (ctrl->id) {
369 case V4L2_CID_BRIGHTNESS:
370 ctrl->val = read_reg(0
371 break;
372 }
373 }
374
375 Note that you use the 'new value' union as wel
376 controls that need to implement g_volatile_ctr
377 are not, a V4L2_EVENT_CTRL_CH_VALUE will not b
378 changes.
379
380 To mark a control as volatile you have to set
381
382 .. code-block:: c
383
384 ctrl = v4l2_ctrl_new_std(&sd->ctrl_han
385 if (ctrl)
386 ctrl->flags |= V4L2_CTRL_FLAG_
387
388 For try/s_ctrl the new values (i.e. as passed
389 you can modify them in try_ctrl or set them in
390 contains the current value, which you can use
391
392 If s_ctrl returns 0 (OK), then the control fra
393 values to the 'cur' union.
394
395 While in g_volatile/s/try_ctrl you can access
396 by the same handler since the handler's lock i
397 the value of controls owned by other handlers,
398 not to introduce deadlocks.
399
400 Outside of the control ops you have to go thro
401 or set a single control value safely in your d
402
403 .. code-block:: c
404
405 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl
406 int v4l2_ctrl_s_ctrl(struct v4l2_ctrl
407
408 These functions go through the control framewo
409 do. Don't use these inside the control ops g_v
410 will result in a deadlock since these helpers
411
412 You can also take the handler lock yourself:
413
414 .. code-block:: c
415
416 mutex_lock(&state->ctrl_handler.lock);
417 pr_info("String value is '%s'\n", ctrl
418 pr_info("Integer value is '%s'\n", ctr
419 mutex_unlock(&state->ctrl_handler.lock
420
421
422 Menu Controls
423 -------------
424
425 The v4l2_ctrl struct contains this union:
426
427 .. code-block:: c
428
429 union {
430 u32 step;
431 u32 menu_skip_mask;
432 };
433
434 For menu controls menu_skip_mask is used. What
435 to easily exclude certain menu items. This is
436 implementation where you can return -EINVAL if
437 present. Note that VIDIOC_QUERYCTRL always ret
438 menu controls.
439
440 A good example is the MPEG Audio Layer II Bitr
441 menu is a list of standardized possible bitrat
442 implementations will only support a subset of
443 mask you can tell the framework which menu ite
444 it to 0 means that all menu items are supporte
445
446 You set this mask either through the v4l2_ctrl
447 control, or by calling v4l2_ctrl_new_std_menu(
448
449
450 Custom Controls
451 ---------------
452
453 Driver specific controls can be created using
454
455 .. code-block:: c
456
457 static const struct v4l2_ctrl_config c
458 .ops = &ctrl_custom_ops,
459 .id = V4L2_CID_MPEG_CX2341X_VI
460 .name = "Spatial Filter",
461 .type = V4L2_CTRL_TYPE_INTEGER
462 .flags = V4L2_CTRL_FLAG_SLIDER
463 .max = 15,
464 .step = 1,
465 };
466
467 ctrl = v4l2_ctrl_new_custom(&foo->ctrl
468
469 The last argument is the priv pointer which ca
470 private data.
471
472 The v4l2_ctrl_config struct also has a field t
473
474 If the name field is not set, then the framewo
475 control and will fill in the name, type and fl
476
477
478 Active and Grabbed Controls
479 ---------------------------
480
481 If you get more complex relationships between
482 activate and deactivate controls. For example,
483 on, then the Chroma Gain control is inactive.
484 the value will not be used by the hardware as
485 control is on. Typically user interfaces can d
486
487 You can set the 'active' status using v4l2_ctr
488 controls are active. Note that the framework d
489 It is meant purely for GUIs. The function is t
490 s_ctrl.
491
492 The other flag is the 'grabbed' flag. A grabbe
493 change it because it is in use by some resourc
494 bitrate controls that cannot be changed while
495
496 If a control is set to 'grabbed' using v4l2_ct
497 will return -EBUSY if an attempt is made to se
498 v4l2_ctrl_grab() function is typically called
499 starts or stops streaming.
500
501
502 Control Clusters
503 ----------------
504
505 By default all controls are independent from t
506 complex scenarios you can get dependencies fro
507 In that case you need to 'cluster' them:
508
509 .. code-block:: c
510
511 struct foo {
512 struct v4l2_ctrl_handler ctrl_
513 #define AUDIO_CL_VOLUME (0)
514 #define AUDIO_CL_MUTE (1)
515 struct v4l2_ctrl *audio_cluste
516 ...
517 };
518
519 state->audio_cluster[AUDIO_CL_VOLUME]
520 v4l2_ctrl_new_std(&state->ctrl
521 state->audio_cluster[AUDIO_CL_MUTE] =
522 v4l2_ctrl_new_std(&state->ctrl
523 v4l2_ctrl_cluster(ARRAY_SIZE(state->au
524
525 From now on whenever one or more of the contro
526 cluster is set (or 'gotten', or 'tried'), only
527 control ('volume' in this example) is called.
528 composite control. Similar to how a 'struct' w
529
530 So when s_ctrl is called with V4L2_CID_AUDIO_V
531 all two controls belonging to the audio_cluste
532
533 .. code-block:: c
534
535 static int foo_s_ctrl(struct v4l2_ctrl
536 {
537 struct foo *state = container_
538
539 switch (ctrl->id) {
540 case V4L2_CID_AUDIO_VOLUME: {
541 struct v4l2_ctrl *mute
542
543 write_reg(0x123, mute-
544 break;
545 }
546 case V4L2_CID_CONTRAST:
547 write_reg(0x456, ctrl-
548 break;
549 }
550 return 0;
551 }
552
553 In the example above the following are equival
554
555 .. code-block:: c
556
557 ctrl == ctrl->cluster[AUDIO_CL_VOLUME]
558 ctrl->cluster[AUDIO_CL_MUTE] == state-
559
560 In practice using cluster arrays like this bec
561 the following equivalent method is used:
562
563 .. code-block:: c
564
565 struct {
566 /* audio cluster */
567 struct v4l2_ctrl *volume;
568 struct v4l2_ctrl *mute;
569 };
570
571 The anonymous struct is used to clearly 'clust
572 but it serves no other purpose. The effect is
573 array with two control pointers. So you can ju
574
575 .. code-block:: c
576
577 state->volume = v4l2_ctrl_new_std(&sta
578 state->mute = v4l2_ctrl_new_std(&state
579 v4l2_ctrl_cluster(2, &state->volume);
580
581 And in foo_s_ctrl you can use these pointers d
582
583 Note that controls in a cluster may be NULL. F
584 reason mute was never added (because the hardw
585 particular feature), then mute will be NULL. S
586 cluster of 2 controls, of which only 1 is actu
587 only restriction is that the first control of
588 present, since that is the 'master' control of
589 control is the one that identifies the cluster
590 pointer to the v4l2_ctrl_ops struct that is us
591
592 Obviously, all controls in the cluster array m
593 a valid control or to NULL.
594
595 In rare cases you might want to know which con
596 were set explicitly by the user. For this you
597 each control. For example, in the case of a vo
598 flag of the mute control would be set if the u
599 mute only. If the user would call VIDIOC_S_EXT
600 controls, then the 'is_new' flag would be 1 fo
601
602 The 'is_new' flag is always 1 when called from
603
604
605 Handling autogain/gain-type Controls with Auto
606 ----------------------------------------------
607
608 A common type of control cluster is one that h
609 controls. Typical examples are autogain/gain,
610 autowhitebalance/red balance/blue balance. In
611 that determines whether another control is han
612 or whether it is under manual control from the
613
614 If the cluster is in automatic mode, then the
615 marked inactive and volatile. When the volatil
616 g_volatile_ctrl operation should return the va
617 mode set up automatically.
618
619 If the cluster is put in manual mode, then the
620 active again and the volatile flag is cleared
621 called while in manual mode). In addition just
622 the current values as determined by the auto m
623 values.
624
625 Finally the V4L2_CTRL_FLAG_UPDATE should be se
626 changing that control affects the control flag
627
628 In order to simplify this a special variation
629 introduced:
630
631 .. code-block:: c
632
633 void v4l2_ctrl_auto_cluster(unsigned n
634 u8 manual_
635
636 The first two arguments are identical to v4l2_
637 tells the framework which value switches the c
638 last argument will optionally set V4L2_CTRL_FL
639 If it is false, then the manual controls are n
640 use that if the hardware does not give you the
641 determined by the auto mode (e.g. if autogain
642 you to obtain the current gain value).
643
644 The first control of the cluster is assumed to
645
646 Using this function will ensure that you don't
647 flag and volatile handling.
648
649
650 VIDIOC_LOG_STATUS Support
651 -------------------------
652
653 This ioctl allow you to dump the current statu
654 The v4l2_ctrl_handler_log_status(ctrl_handler,
655 value of the controls owned by the given handl
656 prefix as well. If the prefix didn't end with
657 for you.
658
659
660 Different Handlers for Different Video Nodes
661 --------------------------------------------
662
663 Usually the V4L2 driver has just one control h
664 all video nodes. But you can also specify diff
665 different video nodes. You can do that by manu
666 field of struct video_device.
667
668 That is no problem if there are no subdevs inv
669 you need to block the automatic merging of sub
670 control handler. You do that by simply setting
671 struct v4l2_device to NULL. Now v4l2_device_re
672 merge subdev controls.
673
674 After each subdev was added, you will then hav
675 manually to add the subdev's control handler (
676 control handler. This control handler may be s
677 for a subset of video_device's. For example: t
678 audio controls, while the video and vbi device
679 handler for the audio and video controls.
680
681 If you want to have one handler (e.g. for a ra
682 of another handler (e.g. for a video device no
683 the controls to the first handler, add the oth
684 handler and finally add the first handler to t
685
686 .. code-block:: c
687
688 v4l2_ctrl_new_std(&radio_ctrl_handler,
689 v4l2_ctrl_new_std(&radio_ctrl_handler,
690 v4l2_ctrl_new_std(&video_ctrl_handler,
691 v4l2_ctrl_new_std(&video_ctrl_handler,
692 v4l2_ctrl_add_handler(&video_ctrl_hand
693
694 The last argument to v4l2_ctrl_add_handler() i
695 you to filter which controls will be added. Se
696 all controls.
697
698 Or you can add specific controls to a handler:
699
700 .. code-block:: c
701
702 volume = v4l2_ctrl_new_std(&video_ctrl
703 v4l2_ctrl_new_std(&video_ctrl_handler,
704 v4l2_ctrl_new_std(&video_ctrl_handler,
705
706 What you should not do is make two identical c
707 For example:
708
709 .. code-block:: c
710
711 v4l2_ctrl_new_std(&radio_ctrl_handler,
712 v4l2_ctrl_new_std(&video_ctrl_handler,
713
714 This would be bad since muting the radio would
715 control. The rule is to have one control for e
716 can twiddle.
717
718
719 Finding Controls
720 ----------------
721
722 Normally you have created the controls yoursel
723 v4l2_ctrl pointer into your own struct.
724
725 But sometimes you need to find a control from
726 not own. For example, if you have to find a vo
727
728 You can do that by calling v4l2_ctrl_find:
729
730 .. code-block:: c
731
732 struct v4l2_ctrl *volume;
733
734 volume = v4l2_ctrl_find(sd->ctrl_handl
735
736 Since v4l2_ctrl_find will lock the handler you
737 use it. For example, this is not a good idea:
738
739 .. code-block:: c
740
741 struct v4l2_ctrl_handler ctrl_handler;
742
743 v4l2_ctrl_new_std(&ctrl_handler, &vide
744 v4l2_ctrl_new_std(&ctrl_handler, &vide
745
746 ...and in video_ops.s_ctrl:
747
748 .. code-block:: c
749
750 case V4L2_CID_BRIGHTNESS:
751 contrast = v4l2_find_ctrl(&ctr
752 ...
753
754 When s_ctrl is called by the framework the ctr
755 attempting to find another control from the sa
756
757 It is recommended not to use this function fro
758
759
760 Preventing Controls inheritance
761 -------------------------------
762
763 When one control handler is added to another u
764 by default all controls from one are merged to
765 have low-level controls that make sense for so
766 not when it is used in consumer-level hardware
767 those low-level controls local to the subdev.
768 setting the 'is_private' flag of the control t
769
770 .. code-block:: c
771
772 static const struct v4l2_ctrl_config c
773 .ops = &ctrl_custom_ops,
774 .id = V4L2_CID_...,
775 .name = "Some Private Control"
776 .type = V4L2_CTRL_TYPE_INTEGER
777 .max = 15,
778 .step = 1,
779 .is_private = 1,
780 };
781
782 ctrl = v4l2_ctrl_new_custom(&foo->ctrl
783
784 These controls will now be skipped when v4l2_c
785
786
787 V4L2_CTRL_TYPE_CTRL_CLASS Controls
788 ----------------------------------
789
790 Controls of this type can be used by GUIs to g
791 A fully featured GUI can make a dialog with mu
792 containing the controls belonging to a particu
793 each tab can be found by querying a special co
794
795 Drivers do not have to care about this. The fr
796 a control of this type whenever the first cont
797 class is added.
798
799
800 Adding Notify Callbacks
801 -----------------------
802
803 Sometimes the platform or bridge driver needs
804 from a sub-device driver changes. You can set
805 this function:
806
807 .. code-block:: c
808
809 void v4l2_ctrl_notify(struct v4l2_ctrl
810 void (*notify)(struct v4l2_ctr
811
812 Whenever the give control changes value the no
813 with a pointer to the control and the priv poi
814 v4l2_ctrl_notify. Note that the control's hand
815 notify function is called.
816
817 There can be only one notify function per cont
818 to set another notify function will cause a WA
819
820 v4l2_ctrl functions and data structures
821 ---------------------------------------
822
823 .. kernel-doc:: include/media/v4l2-ctrls.h
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.