1.. SPDX-License-Identifier: GPL-2.0
2
3V4L2 Controls
4=============
5
6Introduction
7------------
8
9The V4L2 control API seems simple enough, but quickly becomes very hard to
10implement correctly in drivers. But much of the code needed to handle controls
11is actually not driver specific and can be moved to the V4L core framework.
12
13After all, the only part that a driver developer is interested in is:
14
151) How do I add a control?
162) How do I set the control's value? (i.e. s_ctrl)
17
18And occasionally:
19
203) How do I get the control's value? (i.e. g_volatile_ctrl)
214) How do I validate the user's proposed control value? (i.e. try_ctrl)
22
23All the rest is something that can be done centrally.
24
25The control framework was created in order to implement all the rules of the
26V4L2 specification with respect to controls in a central place. And to make
27life as easy as possible for the driver developer.
28
29Note that the control framework relies on the presence of a struct
30:c:type:`v4l2_device` for V4L2 drivers and struct v4l2_subdev for
31sub-device drivers.
32
33
34Objects in the framework
35------------------------
36
37There are two main objects:
38
39The :c:type:`v4l2_ctrl` object describes the control properties and keeps
40track of the control's value (both the current value and the proposed new
41value).
42
43:c:type:`v4l2_ctrl_handler` is the object that keeps track of controls. It
44maintains a list of v4l2_ctrl objects that it owns and another list of
45references to controls, possibly to controls owned by other handlers.
46
47
48Basic usage for V4L2 and sub-device drivers
49-------------------------------------------
50
511) Prepare the driver:
52
53.. code-block:: c
54
55	#include <media/v4l2-ctrls.h>
56
571.1) Add the handler to your driver's top-level struct:
58
59For 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_handler;
68		...
69	};
70
71For 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_handler;
80		...
81	};
82
831.2) Initialize the handler:
84
85.. code-block:: c
86
87	v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
88
89The second argument is a hint telling the function how many controls this
90handler is expected to handle. It will allocate a hashtable based on this
91information. It is a hint only.
92
931.3) Hook the control handler into the driver:
94
95For V4L2 drivers:
96
97.. code-block:: c
98
99	foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;
100
101For sub-device drivers:
102
103.. code-block:: c
104
105	foo->sd.ctrl_handler = &foo->ctrl_handler;
106
1071.4) Clean up the handler at the end:
108
109.. code-block:: c
110
111	v4l2_ctrl_handler_free(&foo->ctrl_handler);
112
113
1142) Add controls:
115
116You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`:
117
118.. code-block:: c
119
120	struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
121			const struct v4l2_ctrl_ops *ops,
122			u32 id, s32 min, s32 max, u32 step, s32 def);
123
124Menu and integer menu controls are added by calling
125:c:func:`v4l2_ctrl_new_std_menu`:
126
127.. code-block:: c
128
129	struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
130			const struct v4l2_ctrl_ops *ops,
131			u32 id, s32 max, s32 skip_mask, s32 def);
132
133Menu controls with a driver specific menu are added by calling
134:c:func:`v4l2_ctrl_new_std_menu_items`:
135
136.. code-block:: c
137
138       struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(
139                       struct v4l2_ctrl_handler *hdl,
140                       const struct v4l2_ctrl_ops *ops, u32 id, s32 max,
141                       s32 skip_mask, s32 def, const char * const *qmenu);
142
143Standard compound controls can be added by calling
144:c:func:`v4l2_ctrl_new_std_compound`:
145
146.. code-block:: c
147
148       struct v4l2_ctrl *v4l2_ctrl_new_std_compound(struct v4l2_ctrl_handler *hdl,
149                       const struct v4l2_ctrl_ops *ops, u32 id,
150                       const union v4l2_ctrl_ptr p_def);
151
152Integer menu controls with a driver specific menu can be added by calling
153:c:func:`v4l2_ctrl_new_int_menu`:
154
155.. code-block:: c
156
157	struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
158			const struct v4l2_ctrl_ops *ops,
159			u32 id, s32 max, s32 def, const s64 *qmenu_int);
160
161These functions are typically called right after the
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_handler, nr_of_controls);
177	v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
178			V4L2_CID_BRIGHTNESS, 0, 255, 1, 128);
179	v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
180			V4L2_CID_CONTRAST, 0, 255, 1, 128);
181	v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops,
182			V4L2_CID_POWER_LINE_FREQUENCY,
183			V4L2_CID_POWER_LINE_FREQUENCY_60HZ, 0,
184			V4L2_CID_POWER_LINE_FREQUENCY_DISABLED);
185	v4l2_ctrl_new_int_menu(&foo->ctrl_handler, &foo_ctrl_ops,
186			V4L2_CID_EXPOSURE_BIAS,
187			ARRAY_SIZE(exp_bias_qmenu) - 1,
188			ARRAY_SIZE(exp_bias_qmenu) / 2 - 1,
189			exp_bias_qmenu);
190	v4l2_ctrl_new_std_menu_items(&foo->ctrl_handler, &foo_ctrl_ops,
191			V4L2_CID_TEST_PATTERN, ARRAY_SIZE(test_pattern) - 1, 0,
192			0, test_pattern);
193	...
194	if (foo->ctrl_handler.error) {
195		int err = foo->ctrl_handler.error;
196
197		v4l2_ctrl_handler_free(&foo->ctrl_handler);
198		return err;
199	}
200
201The :c:func:`v4l2_ctrl_new_std` function returns the v4l2_ctrl pointer to
202the new control, but if you do not need to access the pointer outside the
203control ops, then there is no need to store it.
204
205The :c:func:`v4l2_ctrl_new_std` function will fill in most fields based on
206the control ID except for the min, max, step and default values. These are
207passed in the last four arguments. These values are driver specific while
208control attributes like type, name, flags are all global. The control's
209current value will be set to the default value.
210
211The :c:func:`v4l2_ctrl_new_std_menu` function is very similar but it is
212used for menu controls. There is no min argument since that is always 0 for
213menu controls, and instead of a step there is a skip_mask argument: if bit
214X is 1, then menu item X is skipped.
215
216The :c:func:`v4l2_ctrl_new_int_menu` function creates a new standard
217integer menu control with driver-specific items in the menu. It differs
218from v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and
219takes as the last argument an array of signed 64-bit integers that form an
220exact menu item list.
221
222The :c:func:`v4l2_ctrl_new_std_menu_items` function is very similar to
223v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the
224driver specific menu for an otherwise standard menu control. A good example
225for this control is the test pattern control for capture/display/sensors
226devices that have the capability to generate test patterns. These test
227patterns are hardware specific, so the contents of the menu will vary from
228device to device.
229
230Note that if something fails, the function will return NULL or an error and
231set ctrl_handler->error to the error code. If ctrl_handler->error was already
232set, then it will just return and do nothing. This is also true for
233v4l2_ctrl_handler_init if it cannot allocate the internal data structure.
234
235This makes it easy to init the handler and just add all controls and only check
236the error code at the end. Saves a lot of repetitive error checking.
237
238It is recommended to add controls in ascending control ID order: it will be
239a bit faster that way.
240
2413) Optionally force initial control setup:
242
243.. code-block:: c
244
245	v4l2_ctrl_handler_setup(&foo->ctrl_handler);
246
247This will call s_ctrl for all controls unconditionally. Effectively this
248initializes the hardware to the default control values. It is recommended
249that you do this as this ensures that both the internal data structures and
250the hardware are in sync.
251
2524) Finally: implement the :c:type:`v4l2_ctrl_ops`
253
254.. code-block:: c
255
256	static const struct v4l2_ctrl_ops foo_ctrl_ops = {
257		.s_ctrl = foo_s_ctrl,
258	};
259
260Usually all you need is s_ctrl:
261
262.. code-block:: c
263
264	static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
265	{
266		struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
267
268		switch (ctrl->id) {
269		case V4L2_CID_BRIGHTNESS:
270			write_reg(0x123, ctrl->val);
271			break;
272		case V4L2_CID_CONTRAST:
273			write_reg(0x456, ctrl->val);
274			break;
275		}
276		return 0;
277	}
278
279The control ops are called with the v4l2_ctrl pointer as argument.
280The new control value has already been validated, so all you need to do is
281to actually update the hardware registers.
282
283You're done! And this is sufficient for most of the drivers we have. No need
284to do any validation of control values, or implement QUERYCTRL, QUERY_EXT_CTRL
285and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported.
286
287
288.. note::
289
290   The remainder sections deal with more advanced controls topics and scenarios.
291   In practice the basic usage as described above is sufficient for most drivers.
292
293
294Inheriting Sub-device Controls
295------------------------------
296
297When a sub-device is registered with a V4L2 driver by calling
298v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev
299and v4l2_device are set, then the controls of the subdev will become
300automatically available in the V4L2 driver as well. If the subdev driver
301contains controls that already exist in the V4L2 driver, then those will be
302skipped (so a V4L2 driver can always override a subdev control).
303
304What happens here is that v4l2_device_register_subdev() calls
305v4l2_ctrl_add_handler() adding the controls of the subdev to the controls
306of v4l2_device.
307
308
309Accessing Control Values
310------------------------
311
312The following union is used inside the control framework to access control
313values:
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
324The v4l2_ctrl struct contains these fields that can be used to access both
325current 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
338If the control has a simple s32 type 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
345For all other types use ctrl->p_cur.p<something>. Basically the val
346and cur.val fields can be considered an alias since these are used so often.
347
348Within the control ops you can freely use these. The val and cur.val speak for
349themselves. The p_char pointers point to character buffers of length
350ctrl->maximum + 1, and are always 0-terminated.
351
352Unless the control is marked volatile the p_cur field points to the the
353current cached control value. When you create a new control this value is made
354identical to the default value. After calling v4l2_ctrl_handler_setup() this
355value is passed to the hardware. It is generally a good idea to call this
356function.
357
358Whenever a new value is set that new value is automatically cached. This means
359that most drivers do not need to implement the g_volatile_ctrl() op. The
360exception is for controls that return a volatile register such as a signal
361strength read-out that changes continuously. In that case you will need to
362implement g_volatile_ctrl like this:
363
364.. code-block:: c
365
366	static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl)
367	{
368		switch (ctrl->id) {
369		case V4L2_CID_BRIGHTNESS:
370			ctrl->val = read_reg(0x123);
371			break;
372		}
373	}
374
375Note that you use the 'new value' union as well in g_volatile_ctrl. In general
376controls that need to implement g_volatile_ctrl are read-only controls. If they
377are not, a V4L2_EVENT_CTRL_CH_VALUE will not be generated when the control
378changes.
379
380To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:
381
382.. code-block:: c
383
384	ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);
385	if (ctrl)
386		ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;
387
388For try/s_ctrl the new values (i.e. as passed by the user) are filled in and
389you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union
390contains the current value, which you can use (but not change!) as well.
391
392If s_ctrl returns 0 (OK), then the control framework will copy the new final
393values to the 'cur' union.
394
395While in g_volatile/s/try_ctrl you can access the value of all controls owned
396by the same handler since the handler's lock is held. If you need to access
397the value of controls owned by other handlers, then you have to be very careful
398not to introduce deadlocks.
399
400Outside of the control ops you have to go through to helper functions to get
401or set a single control value safely in your driver:
402
403.. code-block:: c
404
405	s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
406	int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
407
408These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls
409do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that
410will result in a deadlock since these helpers lock the handler as well.
411
412You 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", ctrl1->p_cur.p_char);
418	pr_info("Integer value is '%s'\n", ctrl2->cur.val);
419	mutex_unlock(&state->ctrl_handler.lock);
420
421
422Menu Controls
423-------------
424
425The v4l2_ctrl struct contains this union:
426
427.. code-block:: c
428
429	union {
430		u32 step;
431		u32 menu_skip_mask;
432	};
433
434For menu controls menu_skip_mask is used. What it does is that it allows you
435to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU
436implementation where you can return -EINVAL if a certain menu item is not
437present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for
438menu controls.
439
440A good example is the MPEG Audio Layer II Bitrate menu control where the
441menu is a list of standardized possible bitrates. But in practice hardware
442implementations will only support a subset of those. By setting the skip
443mask you can tell the framework which menu items should be skipped. Setting
444it to 0 means that all menu items are supported.
445
446You set this mask either through the v4l2_ctrl_config struct for a custom
447control, or by calling v4l2_ctrl_new_std_menu().
448
449
450Custom Controls
451---------------
452
453Driver specific controls can be created using v4l2_ctrl_new_custom():
454
455.. code-block:: c
456
457	static const struct v4l2_ctrl_config ctrl_filter = {
458		.ops = &ctrl_custom_ops,
459		.id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER,
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_handler, &ctrl_filter, NULL);
468
469The last argument is the priv pointer which can be set to driver-specific
470private data.
471
472The v4l2_ctrl_config struct also has a field to set the is_private flag.
473
474If the name field is not set, then the framework will assume this is a standard
475control and will fill in the name, type and flags fields accordingly.
476
477
478Active and Grabbed Controls
479---------------------------
480
481If you get more complex relationships between controls, then you may have to
482activate and deactivate controls. For example, if the Chroma AGC control is
483on, then the Chroma Gain control is inactive. That is, you may set it, but
484the value will not be used by the hardware as long as the automatic gain
485control is on. Typically user interfaces can disable such input fields.
486
487You can set the 'active' status using v4l2_ctrl_activate(). By default all
488controls are active. Note that the framework does not check for this flag.
489It is meant purely for GUIs. The function is typically called from within
490s_ctrl.
491
492The other flag is the 'grabbed' flag. A grabbed control means that you cannot
493change it because it is in use by some resource. Typical examples are MPEG
494bitrate controls that cannot be changed while capturing is in progress.
495
496If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework
497will return -EBUSY if an attempt is made to set this control. The
498v4l2_ctrl_grab() function is typically called from the driver when it
499starts or stops streaming.
500
501
502Control Clusters
503----------------
504
505By default all controls are independent from the others. But in more
506complex scenarios you can get dependencies from one control to another.
507In that case you need to 'cluster' them:
508
509.. code-block:: c
510
511	struct foo {
512		struct v4l2_ctrl_handler ctrl_handler;
513	#define AUDIO_CL_VOLUME (0)
514	#define AUDIO_CL_MUTE   (1)
515		struct v4l2_ctrl *audio_cluster[2];
516		...
517	};
518
519	state->audio_cluster[AUDIO_CL_VOLUME] =
520		v4l2_ctrl_new_std(&state->ctrl_handler, ...);
521	state->audio_cluster[AUDIO_CL_MUTE] =
522		v4l2_ctrl_new_std(&state->ctrl_handler, ...);
523	v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster);
524
525From now on whenever one or more of the controls belonging to the same
526cluster is set (or 'gotten', or 'tried'), only the control ops of the first
527control ('volume' in this example) is called. You effectively create a new
528composite control. Similar to how a 'struct' works in C.
529
530So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set
531all two controls belonging to the audio_cluster:
532
533.. code-block:: c
534
535	static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
536	{
537		struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
538
539		switch (ctrl->id) {
540		case V4L2_CID_AUDIO_VOLUME: {
541			struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE];
542
543			write_reg(0x123, mute->val ? 0 : ctrl->val);
544			break;
545		}
546		case V4L2_CID_CONTRAST:
547			write_reg(0x456, ctrl->val);
548			break;
549		}
550		return 0;
551	}
552
553In the example above the following are equivalent for the VOLUME case:
554
555.. code-block:: c
556
557	ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
558	ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
559
560In practice using cluster arrays like this becomes very tiresome. So instead
561the 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
571The anonymous struct is used to clearly 'cluster' these two control pointers,
572but it serves no other purpose. The effect is the same as creating an
573array with two control pointers. So you can just do:
574
575.. code-block:: c
576
577	state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
578	state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
579	v4l2_ctrl_cluster(2, &state->volume);
580
581And in foo_s_ctrl you can use these pointers directly: state->mute->val.
582
583Note that controls in a cluster may be NULL. For example, if for some
584reason mute was never added (because the hardware doesn't support that
585particular feature), then mute will be NULL. So in that case we have a
586cluster of 2 controls, of which only 1 is actually instantiated. The
587only restriction is that the first control of the cluster must always be
588present, since that is the 'master' control of the cluster. The master
589control is the one that identifies the cluster and that provides the
590pointer to the v4l2_ctrl_ops struct that is used for that cluster.
591
592Obviously, all controls in the cluster array must be initialized to either
593a valid control or to NULL.
594
595In rare cases you might want to know which controls of a cluster actually
596were set explicitly by the user. For this you can check the 'is_new' flag of
597each control. For example, in the case of a volume/mute cluster the 'is_new'
598flag of the mute control would be set if the user called VIDIOC_S_CTRL for
599mute only. If the user would call VIDIOC_S_EXT_CTRLS for both mute and volume
600controls, then the 'is_new' flag would be 1 for both controls.
601
602The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup().
603
604
605Handling autogain/gain-type Controls with Auto Clusters
606-------------------------------------------------------
607
608A common type of control cluster is one that handles 'auto-foo/foo'-type
609controls. Typical examples are autogain/gain, autoexposure/exposure,
610autowhitebalance/red balance/blue balance. In all cases you have one control
611that determines whether another control is handled automatically by the hardware,
612or whether it is under manual control from the user.
613
614If the cluster is in automatic mode, then the manual controls should be
615marked inactive and volatile. When the volatile controls are read the
616g_volatile_ctrl operation should return the value that the hardware's automatic
617mode set up automatically.
618
619If the cluster is put in manual mode, then the manual controls should become
620active again and the volatile flag is cleared (so g_volatile_ctrl is no longer
621called while in manual mode). In addition just before switching to manual mode
622the current values as determined by the auto mode are copied as the new manual
623values.
624
625Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since
626changing that control affects the control flags of the manual controls.
627
628In order to simplify this a special variation of v4l2_ctrl_cluster was
629introduced:
630
631.. code-block:: c
632
633	void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
634				    u8 manual_val, bool set_volatile);
635
636The first two arguments are identical to v4l2_ctrl_cluster. The third argument
637tells the framework which value switches the cluster into manual mode. The
638last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls.
639If it is false, then the manual controls are never volatile. You would typically
640use that if the hardware does not give you the option to read back to values as
641determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow
642you to obtain the current gain value).
643
644The first control of the cluster is assumed to be the 'auto' control.
645
646Using this function will ensure that you don't need to handle all the complex
647flag and volatile handling.
648
649
650VIDIOC_LOG_STATUS Support
651-------------------------
652
653This ioctl allow you to dump the current status of a driver to the kernel log.
654The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the
655value of the controls owned by the given handler to the log. You can supply a
656prefix as well. If the prefix didn't end with a space, then ': ' will be added
657for you.
658
659
660Different Handlers for Different Video Nodes
661--------------------------------------------
662
663Usually the V4L2 driver has just one control handler that is global for
664all video nodes. But you can also specify different control handlers for
665different video nodes. You can do that by manually setting the ctrl_handler
666field of struct video_device.
667
668That is no problem if there are no subdevs involved but if there are, then
669you need to block the automatic merging of subdev controls to the global
670control handler. You do that by simply setting the ctrl_handler field in
671struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer
672merge subdev controls.
673
674After each subdev was added, you will then have to call v4l2_ctrl_add_handler
675manually to add the subdev's control handler (sd->ctrl_handler) to the desired
676control handler. This control handler may be specific to the video_device or
677for a subset of video_device's. For example: the radio device nodes only have
678audio controls, while the video and vbi device nodes share the same control
679handler for the audio and video controls.
680
681If you want to have one handler (e.g. for a radio device node) have a subset
682of another handler (e.g. for a video device node), then you should first add
683the controls to the first handler, add the other controls to the second
684handler and finally add the first handler to the second. For example:
685
686.. code-block:: c
687
688	v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...);
689	v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
690	v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
691	v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
692	v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler, NULL);
693
694The last argument to v4l2_ctrl_add_handler() is a filter function that allows
695you to filter which controls will be added. Set it to NULL if you want to add
696all controls.
697
698Or you can add specific controls to a handler:
699
700.. code-block:: c
701
702	volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...);
703	v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...);
704	v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...);
705
706What you should not do is make two identical controls for two handlers.
707For example:
708
709.. code-block:: c
710
711	v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
712	v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...);
713
714This would be bad since muting the radio would not change the video mute
715control. The rule is to have one control for each hardware 'knob' that you
716can twiddle.
717
718
719Finding Controls
720----------------
721
722Normally you have created the controls yourself and you can store the struct
723v4l2_ctrl pointer into your own struct.
724
725But sometimes you need to find a control from another handler that you do
726not own. For example, if you have to find a volume control from a subdev.
727
728You 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_handler, V4L2_CID_AUDIO_VOLUME);
735
736Since v4l2_ctrl_find will lock the handler you have to be careful where you
737use 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, &video_ops, V4L2_CID_BRIGHTNESS, ...);
744	v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
745
746...and in video_ops.s_ctrl:
747
748.. code-block:: c
749
750	case V4L2_CID_BRIGHTNESS:
751		contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST);
752		...
753
754When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so
755attempting to find another control from the same handler will deadlock.
756
757It is recommended not to use this function from inside the control ops.
758
759
760Preventing Controls inheritance
761-------------------------------
762
763When one control handler is added to another using v4l2_ctrl_add_handler, then
764by default all controls from one are merged to the other. But a subdev might
765have low-level controls that make sense for some advanced embedded system, but
766not when it is used in consumer-level hardware. In that case you want to keep
767those low-level controls local to the subdev. You can do this by simply
768setting the 'is_private' flag of the control to 1:
769
770.. code-block:: c
771
772	static const struct v4l2_ctrl_config ctrl_private = {
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_handler, &ctrl_private, NULL);
783
784These controls will now be skipped when v4l2_ctrl_add_handler is called.
785
786
787V4L2_CTRL_TYPE_CTRL_CLASS Controls
788----------------------------------
789
790Controls of this type can be used by GUIs to get the name of the control class.
791A fully featured GUI can make a dialog with multiple tabs with each tab
792containing the controls belonging to a particular control class. The name of
793each tab can be found by querying a special control with ID <control class | 1>.
794
795Drivers do not have to care about this. The framework will automatically add
796a control of this type whenever the first control belonging to a new control
797class is added.
798
799
800Adding Notify Callbacks
801-----------------------
802
803Sometimes the platform or bridge driver needs to be notified when a control
804from a sub-device driver changes. You can set a notify callback by calling
805this function:
806
807.. code-block:: c
808
809	void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl,
810		void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv);
811
812Whenever the give control changes value the notify callback will be called
813with a pointer to the control and the priv pointer that was passed with
814v4l2_ctrl_notify. Note that the control's handler lock is held when the
815notify function is called.
816
817There can be only one notify function per control handler. Any attempt
818to set another notify function will cause a WARN_ON.
819
820v4l2_ctrl functions and data structures
821---------------------------------------
822
823.. kernel-doc:: include/media/v4l2-ctrls.h
824