About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / video4linux / v4l2-controls.txt




Custom Search

Based on kernel version 4.1. Page generated on 2015-06-28 12:14 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.