1 .. SPDX-License-Identifier: GPL-2.0
9 The V4L2 control API seems simple enough, but quickly becomes very hard to
10 implement correctly in drivers. But much of the code needed to handle controls
11 is actually not driver specific and can be moved to the V4L core framework.
13 After all, the only part that a driver developer is interested in is:
15 1) How do I add a control?
16 2) How do I set the control's value? (i.e. s_ctrl)
20 3) How do I get the control's value? (i.e. g_volatile_ctrl)
21 4) How do I validate the user's proposed control value? (i.e. try_ctrl)
23 All the rest is something that can be done centrally.
25 The control framework was created in order to implement all the rules of the
26 V4L2 specification with respect to controls in a central place. And to make
27 life as easy as possible for the driver developer.
29 Note that the control framework relies on the presence of a struct
30 :c:type:`v4l2_device` for V4L2 drivers and struct :c:type:`v4l2_subdev` for
34 Objects in the framework
35 ------------------------
37 There are two main objects:
39 The :c:type:`v4l2_ctrl` object describes the control properties and keeps
40 track of the control's value (both the current value and the proposed new
43 :c:type:`v4l2_ctrl_handler` is the object that keeps track of controls. It
44 maintains a list of v4l2_ctrl objects that it owns and another list of
45 references to controls, possibly to controls owned by other handlers.
48 Basic usage for V4L2 and sub-device drivers
49 -------------------------------------------
51 1) Prepare the driver:
53 1.1) Add the handler to your driver's top-level struct:
59 struct v4l2_ctrl_handler ctrl_handler;
65 1.2) Initialize the handler:
69 v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
71 The second argument is a hint telling the function how many controls this
72 handler is expected to handle. It will allocate a hashtable based on this
73 information. It is a hint only.
75 1.3) Hook the control handler into the driver:
77 1.3.1) For V4L2 drivers do this:
83 struct v4l2_device v4l2_dev;
85 struct v4l2_ctrl_handler ctrl_handler;
89 foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;
91 Where foo->v4l2_dev is of type struct v4l2_device.
93 Finally, remove all control functions from your v4l2_ioctl_ops (if any):
94 vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl,
95 vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls.
96 Those are now no longer needed.
98 1.3.2) For sub-device drivers do this:
104 struct v4l2_subdev sd;
106 struct v4l2_ctrl_handler ctrl_handler;
110 foo->sd.ctrl_handler = &foo->ctrl_handler;
112 Where foo->sd is of type struct v4l2_subdev.
114 1.4) Clean up the handler at the end:
118 v4l2_ctrl_handler_free(&foo->ctrl_handler);
123 You add non-menu controls by calling v4l2_ctrl_new_std:
127 struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
128 const struct v4l2_ctrl_ops *ops,
129 u32 id, s32 min, s32 max, u32 step, s32 def);
131 Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu:
135 struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
136 const struct v4l2_ctrl_ops *ops,
137 u32 id, s32 max, s32 skip_mask, s32 def);
139 Menu controls with a driver specific menu are added by calling
140 v4l2_ctrl_new_std_menu_items:
144 struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(
145 struct v4l2_ctrl_handler *hdl,
146 const struct v4l2_ctrl_ops *ops, u32 id, s32 max,
147 s32 skip_mask, s32 def, const char * const *qmenu);
149 Integer menu controls with a driver specific menu can be added by calling
150 v4l2_ctrl_new_int_menu:
154 struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
155 const struct v4l2_ctrl_ops *ops,
156 u32 id, s32 max, s32 def, const s64 *qmenu_int);
158 These functions are typically called right after the v4l2_ctrl_handler_init:
162 static const s64 exp_bias_qmenu[] = {
165 static const char * const test_pattern[] = {
172 v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
173 v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
174 V4L2_CID_BRIGHTNESS, 0, 255, 1, 128);
175 v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
176 V4L2_CID_CONTRAST, 0, 255, 1, 128);
177 v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops,
178 V4L2_CID_POWER_LINE_FREQUENCY,
179 V4L2_CID_POWER_LINE_FREQUENCY_60HZ, 0,
180 V4L2_CID_POWER_LINE_FREQUENCY_DISABLED);
181 v4l2_ctrl_new_int_menu(&foo->ctrl_handler, &foo_ctrl_ops,
182 V4L2_CID_EXPOSURE_BIAS,
183 ARRAY_SIZE(exp_bias_qmenu) - 1,
184 ARRAY_SIZE(exp_bias_qmenu) / 2 - 1,
186 v4l2_ctrl_new_std_menu_items(&foo->ctrl_handler, &foo_ctrl_ops,
187 V4L2_CID_TEST_PATTERN, ARRAY_SIZE(test_pattern) - 1, 0,
190 if (foo->ctrl_handler.error) {
191 int err = foo->ctrl_handler.error;
193 v4l2_ctrl_handler_free(&foo->ctrl_handler);
197 The v4l2_ctrl_new_std function returns the v4l2_ctrl pointer to the new
198 control, but if you do not need to access the pointer outside the control ops,
199 then there is no need to store it.
201 The v4l2_ctrl_new_std function will fill in most fields based on the control
202 ID except for the min, max, step and default values. These are passed in the
203 last four arguments. These values are driver specific while control attributes
204 like type, name, flags are all global. The control's current value will be set
205 to the default value.
207 The v4l2_ctrl_new_std_menu function is very similar but it is used for menu
208 controls. There is no min argument since that is always 0 for menu controls,
209 and instead of a step there is a skip_mask argument: if bit X is 1, then menu
212 The v4l2_ctrl_new_int_menu function creates a new standard integer menu
213 control with driver-specific items in the menu. It differs from
214 v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and takes
215 as the last argument an array of signed 64-bit integers that form an exact
218 The v4l2_ctrl_new_std_menu_items function is very similar to
219 v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the driver
220 specific menu for an otherwise standard menu control. A good example for this
221 control is the test pattern control for capture/display/sensors devices that
222 have the capability to generate test patterns. These test patterns are hardware
223 specific, so the contents of the menu will vary from device to device.
225 Note that if something fails, the function will return NULL or an error and
226 set ctrl_handler->error to the error code. If ctrl_handler->error was already
227 set, then it will just return and do nothing. This is also true for
228 v4l2_ctrl_handler_init if it cannot allocate the internal data structure.
230 This makes it easy to init the handler and just add all controls and only check
231 the error code at the end. Saves a lot of repetitive error checking.
233 It is recommended to add controls in ascending control ID order: it will be
234 a bit faster that way.
236 3) Optionally force initial control setup:
240 v4l2_ctrl_handler_setup(&foo->ctrl_handler);
242 This will call s_ctrl for all controls unconditionally. Effectively this
243 initializes the hardware to the default control values. It is recommended
244 that you do this as this ensures that both the internal data structures and
245 the hardware are in sync.
247 4) Finally: implement the :c:type:`v4l2_ctrl_ops`
251 static const struct v4l2_ctrl_ops foo_ctrl_ops = {
252 .s_ctrl = foo_s_ctrl,
255 Usually all you need is s_ctrl:
259 static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
261 struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
264 case V4L2_CID_BRIGHTNESS:
265 write_reg(0x123, ctrl->val);
267 case V4L2_CID_CONTRAST:
268 write_reg(0x456, ctrl->val);
274 The control ops are called with the v4l2_ctrl pointer as argument.
275 The new control value has already been validated, so all you need to do is
276 to actually update the hardware registers.
278 You're done! And this is sufficient for most of the drivers we have. No need
279 to do any validation of control values, or implement QUERYCTRL, QUERY_EXT_CTRL
280 and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported.
285 The remainder sections deal with more advanced controls topics and scenarios.
286 In practice the basic usage as described above is sufficient for most drivers.
292 When a sub-device is registered with a V4L2 driver by calling
293 v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev
294 and v4l2_device are set, then the controls of the subdev will become
295 automatically available in the V4L2 driver as well. If the subdev driver
296 contains controls that already exist in the V4L2 driver, then those will be
297 skipped (so a V4L2 driver can always override a subdev control).
299 What happens here is that v4l2_device_register_subdev() calls
300 v4l2_ctrl_add_handler() adding the controls of the subdev to the controls
304 Accessing Control Values
305 ------------------------
307 The following union is used inside the control framework to access control
312 union v4l2_ctrl_ptr {
319 The v4l2_ctrl struct contains these fields that can be used to access both
320 current and new values:
330 union v4l2_ctrl_ptr p_new;
331 union v4l2_ctrl_ptr p_cur;
333 If the control has a simple s32 type type, then:
337 &ctrl->val == ctrl->p_new.p_s32
338 &ctrl->cur.val == ctrl->p_cur.p_s32
340 For all other types use ctrl->p_cur.p<something>. Basically the val
341 and cur.val fields can be considered an alias since these are used so often.
343 Within the control ops you can freely use these. The val and cur.val speak for
344 themselves. The p_char pointers point to character buffers of length
345 ctrl->maximum + 1, and are always 0-terminated.
347 Unless the control is marked volatile the p_cur field points to the the
348 current cached control value. When you create a new control this value is made
349 identical to the default value. After calling v4l2_ctrl_handler_setup() this
350 value is passed to the hardware. It is generally a good idea to call this
353 Whenever a new value is set that new value is automatically cached. This means
354 that most drivers do not need to implement the g_volatile_ctrl() op. The
355 exception is for controls that return a volatile register such as a signal
356 strength read-out that changes continuously. In that case you will need to
357 implement g_volatile_ctrl like this:
361 static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl)
364 case V4L2_CID_BRIGHTNESS:
365 ctrl->val = read_reg(0x123);
370 Note that you use the 'new value' union as well in g_volatile_ctrl. In general
371 controls that need to implement g_volatile_ctrl are read-only controls. If they
372 are not, a V4L2_EVENT_CTRL_CH_VALUE will not be generated when the control
375 To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:
379 ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);
381 ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;
383 For try/s_ctrl the new values (i.e. as passed by the user) are filled in and
384 you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union
385 contains the current value, which you can use (but not change!) as well.
387 If s_ctrl returns 0 (OK), then the control framework will copy the new final
388 values to the 'cur' union.
390 While in g_volatile/s/try_ctrl you can access the value of all controls owned
391 by the same handler since the handler's lock is held. If you need to access
392 the value of controls owned by other handlers, then you have to be very careful
393 not to introduce deadlocks.
395 Outside of the control ops you have to go through to helper functions to get
396 or set a single control value safely in your driver:
400 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
401 int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
403 These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls
404 do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that
405 will result in a deadlock since these helpers lock the handler as well.
407 You can also take the handler lock yourself:
411 mutex_lock(&state->ctrl_handler.lock);
412 pr_info("String value is '%s'\n", ctrl1->p_cur.p_char);
413 pr_info("Integer value is '%s'\n", ctrl2->cur.val);
414 mutex_unlock(&state->ctrl_handler.lock);
420 The v4l2_ctrl struct contains this union:
429 For menu controls menu_skip_mask is used. What it does is that it allows you
430 to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU
431 implementation where you can return -EINVAL if a certain menu item is not
432 present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for
435 A good example is the MPEG Audio Layer II Bitrate menu control where the
436 menu is a list of standardized possible bitrates. But in practice hardware
437 implementations will only support a subset of those. By setting the skip
438 mask you can tell the framework which menu items should be skipped. Setting
439 it to 0 means that all menu items are supported.
441 You set this mask either through the v4l2_ctrl_config struct for a custom
442 control, or by calling v4l2_ctrl_new_std_menu().
448 Driver specific controls can be created using v4l2_ctrl_new_custom():
452 static const struct v4l2_ctrl_config ctrl_filter = {
453 .ops = &ctrl_custom_ops,
454 .id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER,
455 .name = "Spatial Filter",
456 .type = V4L2_CTRL_TYPE_INTEGER,
457 .flags = V4L2_CTRL_FLAG_SLIDER,
462 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL);
464 The last argument is the priv pointer which can be set to driver-specific
467 The v4l2_ctrl_config struct also has a field to set the is_private flag.
469 If the name field is not set, then the framework will assume this is a standard
470 control and will fill in the name, type and flags fields accordingly.
473 Active and Grabbed Controls
474 ---------------------------
476 If you get more complex relationships between controls, then you may have to
477 activate and deactivate controls. For example, if the Chroma AGC control is
478 on, then the Chroma Gain control is inactive. That is, you may set it, but
479 the value will not be used by the hardware as long as the automatic gain
480 control is on. Typically user interfaces can disable such input fields.
482 You can set the 'active' status using v4l2_ctrl_activate(). By default all
483 controls are active. Note that the framework does not check for this flag.
484 It is meant purely for GUIs. The function is typically called from within
487 The other flag is the 'grabbed' flag. A grabbed control means that you cannot
488 change it because it is in use by some resource. Typical examples are MPEG
489 bitrate controls that cannot be changed while capturing is in progress.
491 If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework
492 will return -EBUSY if an attempt is made to set this control. The
493 v4l2_ctrl_grab() function is typically called from the driver when it
494 starts or stops streaming.
500 By default all controls are independent from the others. But in more
501 complex scenarios you can get dependencies from one control to another.
502 In that case you need to 'cluster' them:
507 struct v4l2_ctrl_handler ctrl_handler;
508 #define AUDIO_CL_VOLUME (0)
509 #define AUDIO_CL_MUTE (1)
510 struct v4l2_ctrl *audio_cluster[2];
514 state->audio_cluster[AUDIO_CL_VOLUME] =
515 v4l2_ctrl_new_std(&state->ctrl_handler, ...);
516 state->audio_cluster[AUDIO_CL_MUTE] =
517 v4l2_ctrl_new_std(&state->ctrl_handler, ...);
518 v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster);
520 From now on whenever one or more of the controls belonging to the same
521 cluster is set (or 'gotten', or 'tried'), only the control ops of the first
522 control ('volume' in this example) is called. You effectively create a new
523 composite control. Similar to how a 'struct' works in C.
525 So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set
526 all two controls belonging to the audio_cluster:
530 static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
532 struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
535 case V4L2_CID_AUDIO_VOLUME: {
536 struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE];
538 write_reg(0x123, mute->val ? 0 : ctrl->val);
541 case V4L2_CID_CONTRAST:
542 write_reg(0x456, ctrl->val);
548 In the example above the following are equivalent for the VOLUME case:
552 ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
553 ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
555 In practice using cluster arrays like this becomes very tiresome. So instead
556 the following equivalent method is used:
562 struct v4l2_ctrl *volume;
563 struct v4l2_ctrl *mute;
566 The anonymous struct is used to clearly 'cluster' these two control pointers,
567 but it serves no other purpose. The effect is the same as creating an
568 array with two control pointers. So you can just do:
572 state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
573 state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
574 v4l2_ctrl_cluster(2, &state->volume);
576 And in foo_s_ctrl you can use these pointers directly: state->mute->val.
578 Note that controls in a cluster may be NULL. For example, if for some
579 reason mute was never added (because the hardware doesn't support that
580 particular feature), then mute will be NULL. So in that case we have a
581 cluster of 2 controls, of which only 1 is actually instantiated. The
582 only restriction is that the first control of the cluster must always be
583 present, since that is the 'master' control of the cluster. The master
584 control is the one that identifies the cluster and that provides the
585 pointer to the v4l2_ctrl_ops struct that is used for that cluster.
587 Obviously, all controls in the cluster array must be initialized to either
588 a valid control or to NULL.
590 In rare cases you might want to know which controls of a cluster actually
591 were set explicitly by the user. For this you can check the 'is_new' flag of
592 each control. For example, in the case of a volume/mute cluster the 'is_new'
593 flag of the mute control would be set if the user called VIDIOC_S_CTRL for
594 mute only. If the user would call VIDIOC_S_EXT_CTRLS for both mute and volume
595 controls, then the 'is_new' flag would be 1 for both controls.
597 The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup().
600 Handling autogain/gain-type Controls with Auto Clusters
601 -------------------------------------------------------
603 A common type of control cluster is one that handles 'auto-foo/foo'-type
604 controls. Typical examples are autogain/gain, autoexposure/exposure,
605 autowhitebalance/red balance/blue balance. In all cases you have one control
606 that determines whether another control is handled automatically by the hardware,
607 or whether it is under manual control from the user.
609 If the cluster is in automatic mode, then the manual controls should be
610 marked inactive and volatile. When the volatile controls are read the
611 g_volatile_ctrl operation should return the value that the hardware's automatic
612 mode set up automatically.
614 If the cluster is put in manual mode, then the manual controls should become
615 active again and the volatile flag is cleared (so g_volatile_ctrl is no longer
616 called while in manual mode). In addition just before switching to manual mode
617 the current values as determined by the auto mode are copied as the new manual
620 Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since
621 changing that control affects the control flags of the manual controls.
623 In order to simplify this a special variation of v4l2_ctrl_cluster was
628 void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
629 u8 manual_val, bool set_volatile);
631 The first two arguments are identical to v4l2_ctrl_cluster. The third argument
632 tells the framework which value switches the cluster into manual mode. The
633 last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls.
634 If it is false, then the manual controls are never volatile. You would typically
635 use that if the hardware does not give you the option to read back to values as
636 determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow
637 you to obtain the current gain value).
639 The first control of the cluster is assumed to be the 'auto' control.
641 Using this function will ensure that you don't need to handle all the complex
642 flag and volatile handling.
645 VIDIOC_LOG_STATUS Support
646 -------------------------
648 This ioctl allow you to dump the current status of a driver to the kernel log.
649 The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the
650 value of the controls owned by the given handler to the log. You can supply a
651 prefix as well. If the prefix didn't end with a space, then ': ' will be added
655 Different Handlers for Different Video Nodes
656 --------------------------------------------
658 Usually the V4L2 driver has just one control handler that is global for
659 all video nodes. But you can also specify different control handlers for
660 different video nodes. You can do that by manually setting the ctrl_handler
661 field of struct video_device.
663 That is no problem if there are no subdevs involved but if there are, then
664 you need to block the automatic merging of subdev controls to the global
665 control handler. You do that by simply setting the ctrl_handler field in
666 struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer
667 merge subdev controls.
669 After each subdev was added, you will then have to call v4l2_ctrl_add_handler
670 manually to add the subdev's control handler (sd->ctrl_handler) to the desired
671 control handler. This control handler may be specific to the video_device or
672 for a subset of video_device's. For example: the radio device nodes only have
673 audio controls, while the video and vbi device nodes share the same control
674 handler for the audio and video controls.
676 If you want to have one handler (e.g. for a radio device node) have a subset
677 of another handler (e.g. for a video device node), then you should first add
678 the controls to the first handler, add the other controls to the second
679 handler and finally add the first handler to the second. For example:
683 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...);
684 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
685 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
686 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
687 v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler, NULL);
689 The last argument to v4l2_ctrl_add_handler() is a filter function that allows
690 you to filter which controls will be added. Set it to NULL if you want to add
693 Or you can add specific controls to a handler:
697 volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...);
698 v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...);
699 v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...);
701 What you should not do is make two identical controls for two handlers.
706 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
707 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...);
709 This would be bad since muting the radio would not change the video mute
710 control. The rule is to have one control for each hardware 'knob' that you
717 Normally you have created the controls yourself and you can store the struct
718 v4l2_ctrl pointer into your own struct.
720 But sometimes you need to find a control from another handler that you do
721 not own. For example, if you have to find a volume control from a subdev.
723 You can do that by calling v4l2_ctrl_find:
727 struct v4l2_ctrl *volume;
729 volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME);
731 Since v4l2_ctrl_find will lock the handler you have to be careful where you
732 use it. For example, this is not a good idea:
736 struct v4l2_ctrl_handler ctrl_handler;
738 v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
739 v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
741 ...and in video_ops.s_ctrl:
745 case V4L2_CID_BRIGHTNESS:
746 contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST);
749 When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so
750 attempting to find another control from the same handler will deadlock.
752 It is recommended not to use this function from inside the control ops.
758 When one control handler is added to another using v4l2_ctrl_add_handler, then
759 by default all controls from one are merged to the other. But a subdev might
760 have low-level controls that make sense for some advanced embedded system, but
761 not when it is used in consumer-level hardware. In that case you want to keep
762 those low-level controls local to the subdev. You can do this by simply
763 setting the 'is_private' flag of the control to 1:
767 static const struct v4l2_ctrl_config ctrl_private = {
768 .ops = &ctrl_custom_ops,
770 .name = "Some Private Control",
771 .type = V4L2_CTRL_TYPE_INTEGER,
777 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL);
779 These controls will now be skipped when v4l2_ctrl_add_handler is called.
782 V4L2_CTRL_TYPE_CTRL_CLASS Controls
783 ----------------------------------
785 Controls of this type can be used by GUIs to get the name of the control class.
786 A fully featured GUI can make a dialog with multiple tabs with each tab
787 containing the controls belonging to a particular control class. The name of
788 each tab can be found by querying a special control with ID <control class | 1>.
790 Drivers do not have to care about this. The framework will automatically add
791 a control of this type whenever the first control belonging to a new control
795 Adding Notify Callbacks
796 -----------------------
798 Sometimes the platform or bridge driver needs to be notified when a control
799 from a sub-device driver changes. You can set a notify callback by calling
804 void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl,
805 void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv);
807 Whenever the give control changes value the notify callback will be called
808 with a pointer to the control and the priv pointer that was passed with
809 v4l2_ctrl_notify. Note that the control's handler lock is held when the
810 notify function is called.
812 There can be only one notify function per control handler. Any attempt
813 to set another notify function will cause a WARN_ON.
815 v4l2_ctrl functions and data structures
816 ---------------------------------------
818 .. kernel-doc:: include/media/v4l2-ctrls.h