blob: 0f84ce8c9a7b1389c4c9b34fd9b5f427bdb22c40 [file] [log] [blame]
Hans Verkuila42b57f2010-08-01 14:35:53 -03001Introduction
2============
3
4The V4L2 control API seems simple enough, but quickly becomes very hard to
5implement correctly in drivers. But much of the code needed to handle controls
6is actually not driver specific and can be moved to the V4L core framework.
7
8After all, the only part that a driver developer is interested in is:
9
101) How do I add a control?
112) How do I set the control's value? (i.e. s_ctrl)
12
13And occasionally:
14
153) How do I get the control's value? (i.e. g_volatile_ctrl)
164) How do I validate the user's proposed control value? (i.e. try_ctrl)
17
18All the rest is something that can be done centrally.
19
20The control framework was created in order to implement all the rules of the
21V4L2 specification with respect to controls in a central place. And to make
22life as easy as possible for the driver developer.
23
24Note that the control framework relies on the presence of a struct v4l2_device
25for V4L2 drivers and struct v4l2_subdev for sub-device drivers.
26
27
28Objects in the framework
29========================
30
31There are two main objects:
32
33The v4l2_ctrl object describes the control properties and keeps track of the
34control's value (both the current value and the proposed new value).
35
36v4l2_ctrl_handler is the object that keeps track of controls. It maintains a
37list of v4l2_ctrl objects that it owns and another list of references to
38controls, possibly to controls owned by other handlers.
39
40
41Basic usage for V4L2 and sub-device drivers
42===========================================
43
441) Prepare the driver:
45
461.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
561.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
641.3) Hook the control handler into the driver:
65
661.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
Hans Verkuil04d8b042014-01-20 07:21:31 -030080 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.
Hans Verkuila42b57f2010-08-01 14:35:53 -030083 Those are now no longer needed.
84
851.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
1141.4) Clean up the handler at the end:
115
116 v4l2_ctrl_handler_free(&foo->ctrl_handler);
117
118
1192) Add controls:
120
121You 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
Sylwester Nawrockid1e9b7c2013-07-09 01:24:40 -0300127Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu:
Hans Verkuila42b57f2010-08-01 14:35:53 -0300128
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
Sylwester Nawrockid1e9b7c2013-07-09 01:24:40 -0300133Menu controls with a driver specific menu are added by calling
134v4l2_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
141Integer menu controls with a driver specific menu can be added by calling
142v4l2_ctrl_new_int_menu:
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300143
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
Hans Verkuila42b57f2010-08-01 14:35:53 -0300148These functions are typically called right after the v4l2_ctrl_handler_init:
149
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300150 static const s64 exp_bias_qmenu[] = {
151 -2, -1, 0, 1, 2
152 };
Lad, Prabhakar117a7112012-09-18 15:54:38 -0300153 static const char * const test_pattern[] = {
154 "Disabled",
155 "Vertical Bars",
156 "Solid Black",
157 "Solid White",
158 };
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300159
Hans Verkuila42b57f2010-08-01 14:35:53 -0300160 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);
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300169 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);
Lad, Prabhakar117a7112012-09-18 15:54:38 -0300174 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);
Hans Verkuila42b57f2010-08-01 14:35:53 -0300177 ...
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
185The v4l2_ctrl_new_std function returns the v4l2_ctrl pointer to the new
186control, but if you do not need to access the pointer outside the control ops,
187then there is no need to store it.
188
189The v4l2_ctrl_new_std function will fill in most fields based on the control
190ID except for the min, max, step and default values. These are passed in the
191last four arguments. These values are driver specific while control attributes
192like type, name, flags are all global. The control's current value will be set
193to the default value.
194
195The v4l2_ctrl_new_std_menu function is very similar but it is used for menu
196controls. There is no min argument since that is always 0 for menu controls,
197and instead of a step there is a skip_mask argument: if bit X is 1, then menu
198item X is skipped.
199
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300200The v4l2_ctrl_new_int_menu function creates a new standard integer menu
201control with driver-specific items in the menu. It differs from
202v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and takes
203as the last argument an array of signed 64-bit integers that form an exact
204menu item list.
205
Lad, Prabhakar117a7112012-09-18 15:54:38 -0300206The v4l2_ctrl_new_std_menu_items function is very similar to
207v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the driver
208specific menu for an otherwise standard menu control. A good example for this
209control is the test pattern control for capture/display/sensors devices that
210have the capability to generate test patterns. These test patterns are hardware
211specific, so the contents of the menu will vary from device to device.
212
Hans Verkuila42b57f2010-08-01 14:35:53 -0300213Note that if something fails, the function will return NULL or an error and
214set ctrl_handler->error to the error code. If ctrl_handler->error was already
215set, then it will just return and do nothing. This is also true for
216v4l2_ctrl_handler_init if it cannot allocate the internal data structure.
217
218This makes it easy to init the handler and just add all controls and only check
219the error code at the end. Saves a lot of repetitive error checking.
220
221It is recommended to add controls in ascending control ID order: it will be
222a bit faster that way.
223
2243) Optionally force initial control setup:
225
226 v4l2_ctrl_handler_setup(&foo->ctrl_handler);
227
228This will call s_ctrl for all controls unconditionally. Effectively this
229initializes the hardware to the default control values. It is recommended
230that you do this as this ensures that both the internal data structures and
231the hardware are in sync.
232
2334) 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
239Usually 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
256The control ops are called with the v4l2_ctrl pointer as argument.
257The new control value has already been validated, so all you need to do is
258to actually update the hardware registers.
259
260You're done! And this is sufficient for most of the drivers we have. No need
Hans Verkuil04d8b042014-01-20 07:21:31 -0300261to do any validation of control values, or implement QUERYCTRL, QUERY_EXT_CTRL
262and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported.
Hans Verkuila42b57f2010-08-01 14:35:53 -0300263
264
265==============================================================================
266
267The remainder of this document deals with more advanced topics and scenarios.
268In practice the basic usage as described above is sufficient for most drivers.
269
270===============================================================================
271
272
273Inheriting Controls
274===================
275
276When a sub-device is registered with a V4L2 driver by calling
277v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev
278and v4l2_device are set, then the controls of the subdev will become
279automatically available in the V4L2 driver as well. If the subdev driver
280contains controls that already exist in the V4L2 driver, then those will be
281skipped (so a V4L2 driver can always override a subdev control).
282
283What happens here is that v4l2_device_register_subdev() calls
284v4l2_ctrl_add_handler() adding the controls of the subdev to the controls
285of v4l2_device.
286
287
288Accessing Control Values
289========================
290
Hans Verkuil04d8b042014-01-20 07:21:31 -0300291The following union is used inside the control framework to access control
292values:
Hans Verkuila42b57f2010-08-01 14:35:53 -0300293
Hans Verkuil04d8b042014-01-20 07:21:31 -0300294union v4l2_ctrl_ptr {
295 s32 *p_s32;
296 s64 *p_s64;
297 char *p_char;
298 void *p;
299};
300
301The v4l2_ctrl struct contains these fields that can be used to access both
302current and new values:
303
304 s32 val;
305 struct {
Hans Verkuila42b57f2010-08-01 14:35:53 -0300306 s32 val;
Hans Verkuila42b57f2010-08-01 14:35:53 -0300307 } cur;
308
Hans Verkuila42b57f2010-08-01 14:35:53 -0300309
Hans Verkuil04d8b042014-01-20 07:21:31 -0300310 union v4l2_ctrl_ptr p_new;
311 union v4l2_ctrl_ptr p_cur;
312
313If 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
318For all other types use ctrl->p_cur.p<something>. Basically the val
319and cur.val fields can be considered an alias since these are used so often.
320
321Within the control ops you can freely use these. The val and cur.val speak for
322themselves. The p_char pointers point to character buffers of length
Hans Verkuila42b57f2010-08-01 14:35:53 -0300323ctrl->maximum + 1, and are always 0-terminated.
324
Hans Verkuil04d8b042014-01-20 07:21:31 -0300325Unless the control is marked volatile the p_cur field points to the the
326current cached control value. When you create a new control this value is made
327identical to the default value. After calling v4l2_ctrl_handler_setup() this
328value is passed to the hardware. It is generally a good idea to call this
329function.
Hans Verkuila42b57f2010-08-01 14:35:53 -0300330
331Whenever a new value is set that new value is automatically cached. This means
332that most drivers do not need to implement the g_volatile_ctrl() op. The
333exception is for controls that return a volatile register such as a signal
334strength read-out that changes continuously. In that case you will need to
335implement 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:
Hans Verkuil78866ef2011-05-27 08:53:37 -0300341 ctrl->val = read_reg(0x123);
Hans Verkuila42b57f2010-08-01 14:35:53 -0300342 break;
343 }
344 }
345
Hans Verkuil78866ef2011-05-27 08:53:37 -0300346Note that you use the 'new value' union as well in g_volatile_ctrl. In general
347controls that need to implement g_volatile_ctrl are read-only controls.
Hans Verkuil2a863792011-01-11 14:45:03 -0300348
Hans Verkuil88365102011-08-26 07:35:14 -0300349To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:
Hans Verkuila42b57f2010-08-01 14:35:53 -0300350
351 ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);
352 if (ctrl)
Hans Verkuil88365102011-08-26 07:35:14 -0300353 ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;
Hans Verkuila42b57f2010-08-01 14:35:53 -0300354
355For try/s_ctrl the new values (i.e. as passed by the user) are filled in and
356you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union
357contains the current value, which you can use (but not change!) as well.
358
359If s_ctrl returns 0 (OK), then the control framework will copy the new final
360values to the 'cur' union.
361
362While in g_volatile/s/try_ctrl you can access the value of all controls owned
363by the same handler since the handler's lock is held. If you need to access
364the value of controls owned by other handlers, then you have to be very careful
365not to introduce deadlocks.
366
367Outside of the control ops you have to go through to helper functions to get
368or set a single control value safely in your driver:
369
370 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
371 int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
372
373These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls
374do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that
375will result in a deadlock since these helpers lock the handler as well.
376
377You can also take the handler lock yourself:
378
379 mutex_lock(&state->ctrl_handler.lock);
Hans Verkuil2a9ec372014-04-27 03:38:13 -0300380 pr_info("String value is '%s'\n", ctrl1->p_cur.p_char);
Hans Verkuil04d8b042014-01-20 07:21:31 -0300381 pr_info("Integer value is '%s'\n", ctrl2->cur.val);
Hans Verkuila42b57f2010-08-01 14:35:53 -0300382 mutex_unlock(&state->ctrl_handler.lock);
383
384
385Menu Controls
386=============
387
388The v4l2_ctrl struct contains this union:
389
390 union {
391 u32 step;
392 u32 menu_skip_mask;
393 };
394
395For menu controls menu_skip_mask is used. What it does is that it allows you
396to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU
397implementation where you can return -EINVAL if a certain menu item is not
398present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for
399menu controls.
400
401A good example is the MPEG Audio Layer II Bitrate menu control where the
402menu is a list of standardized possible bitrates. But in practice hardware
403implementations will only support a subset of those. By setting the skip
404mask you can tell the framework which menu items should be skipped. Setting
405it to 0 means that all menu items are supported.
406
407You set this mask either through the v4l2_ctrl_config struct for a custom
408control, or by calling v4l2_ctrl_new_std_menu().
409
410
411Custom Controls
412===============
413
414Driver specific controls can be created using v4l2_ctrl_new_custom():
415
416 static const struct v4l2_ctrl_config ctrl_filter = {
417 .ops = &ctrl_custom_ops,
418 .id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER,
419 .name = "Spatial Filter",
420 .type = V4L2_CTRL_TYPE_INTEGER,
421 .flags = V4L2_CTRL_FLAG_SLIDER,
422 .max = 15,
423 .step = 1,
424 };
425
426 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL);
427
428The last argument is the priv pointer which can be set to driver-specific
429private data.
430
Hans Verkuil88365102011-08-26 07:35:14 -0300431The v4l2_ctrl_config struct also has a field to set the is_private flag.
Hans Verkuila42b57f2010-08-01 14:35:53 -0300432
433If the name field is not set, then the framework will assume this is a standard
434control and will fill in the name, type and flags fields accordingly.
435
436
437Active and Grabbed Controls
438===========================
439
440If you get more complex relationships between controls, then you may have to
441activate and deactivate controls. For example, if the Chroma AGC control is
442on, then the Chroma Gain control is inactive. That is, you may set it, but
443the value will not be used by the hardware as long as the automatic gain
444control is on. Typically user interfaces can disable such input fields.
445
446You can set the 'active' status using v4l2_ctrl_activate(). By default all
447controls are active. Note that the framework does not check for this flag.
448It is meant purely for GUIs. The function is typically called from within
449s_ctrl.
450
451The other flag is the 'grabbed' flag. A grabbed control means that you cannot
452change it because it is in use by some resource. Typical examples are MPEG
453bitrate controls that cannot be changed while capturing is in progress.
454
455If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework
456will return -EBUSY if an attempt is made to set this control. The
457v4l2_ctrl_grab() function is typically called from the driver when it
458starts or stops streaming.
459
460
461Control Clusters
462================
463
464By default all controls are independent from the others. But in more
465complex scenarios you can get dependencies from one control to another.
466In that case you need to 'cluster' them:
467
468 struct foo {
469 struct v4l2_ctrl_handler ctrl_handler;
470#define AUDIO_CL_VOLUME (0)
471#define AUDIO_CL_MUTE (1)
472 struct v4l2_ctrl *audio_cluster[2];
473 ...
474 };
475
476 state->audio_cluster[AUDIO_CL_VOLUME] =
477 v4l2_ctrl_new_std(&state->ctrl_handler, ...);
478 state->audio_cluster[AUDIO_CL_MUTE] =
479 v4l2_ctrl_new_std(&state->ctrl_handler, ...);
480 v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster);
481
482From now on whenever one or more of the controls belonging to the same
483cluster is set (or 'gotten', or 'tried'), only the control ops of the first
484control ('volume' in this example) is called. You effectively create a new
485composite control. Similar to how a 'struct' works in C.
486
487So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set
488all two controls belonging to the audio_cluster:
489
490 static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
491 {
492 struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
493
494 switch (ctrl->id) {
495 case V4L2_CID_AUDIO_VOLUME: {
496 struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE];
497
498 write_reg(0x123, mute->val ? 0 : ctrl->val);
499 break;
500 }
501 case V4L2_CID_CONTRAST:
502 write_reg(0x456, ctrl->val);
503 break;
504 }
505 return 0;
506 }
507
508In the example above the following are equivalent for the VOLUME case:
509
510 ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
511 ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
512
Hans Verkuilc76cd632011-06-07 05:46:53 -0300513In practice using cluster arrays like this becomes very tiresome. So instead
514the following equivalent method is used:
515
516 struct {
517 /* audio cluster */
518 struct v4l2_ctrl *volume;
519 struct v4l2_ctrl *mute;
520 };
521
522The anonymous struct is used to clearly 'cluster' these two control pointers,
523but it serves no other purpose. The effect is the same as creating an
524array with two control pointers. So you can just do:
525
526 state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
527 state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
528 v4l2_ctrl_cluster(2, &state->volume);
529
530And in foo_s_ctrl you can use these pointers directly: state->mute->val.
531
Hans Verkuila42b57f2010-08-01 14:35:53 -0300532Note that controls in a cluster may be NULL. For example, if for some
533reason mute was never added (because the hardware doesn't support that
534particular feature), then mute will be NULL. So in that case we have a
535cluster of 2 controls, of which only 1 is actually instantiated. The
536only restriction is that the first control of the cluster must always be
537present, since that is the 'master' control of the cluster. The master
538control is the one that identifies the cluster and that provides the
539pointer to the v4l2_ctrl_ops struct that is used for that cluster.
540
541Obviously, all controls in the cluster array must be initialized to either
542a valid control or to NULL.
543
Hans Verkuil2a863792011-01-11 14:45:03 -0300544In rare cases you might want to know which controls of a cluster actually
545were set explicitly by the user. For this you can check the 'is_new' flag of
546each control. For example, in the case of a volume/mute cluster the 'is_new'
547flag of the mute control would be set if the user called VIDIOC_S_CTRL for
548mute only. If the user would call VIDIOC_S_EXT_CTRLS for both mute and volume
549controls, then the 'is_new' flag would be 1 for both controls.
550
551The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup().
552
Hans Verkuila42b57f2010-08-01 14:35:53 -0300553
Hans Verkuilc76cd632011-06-07 05:46:53 -0300554Handling autogain/gain-type Controls with Auto Clusters
555=======================================================
556
557A common type of control cluster is one that handles 'auto-foo/foo'-type
558controls. Typical examples are autogain/gain, autoexposure/exposure,
Hans Verkuil882a9352011-08-26 08:35:59 -0300559autowhitebalance/red balance/blue balance. In all cases you have one control
Hans Verkuilc76cd632011-06-07 05:46:53 -0300560that determines whether another control is handled automatically by the hardware,
561or whether it is under manual control from the user.
562
563If the cluster is in automatic mode, then the manual controls should be
Hans Verkuil882a9352011-08-26 08:35:59 -0300564marked inactive and volatile. When the volatile controls are read the
565g_volatile_ctrl operation should return the value that the hardware's automatic
566mode set up automatically.
Hans Verkuilc76cd632011-06-07 05:46:53 -0300567
568If the cluster is put in manual mode, then the manual controls should become
Hans Verkuil882a9352011-08-26 08:35:59 -0300569active again and the volatile flag is cleared (so g_volatile_ctrl is no longer
570called while in manual mode). In addition just before switching to manual mode
571the current values as determined by the auto mode are copied as the new manual
572values.
Hans Verkuilc76cd632011-06-07 05:46:53 -0300573
574Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since
575changing that control affects the control flags of the manual controls.
576
577In order to simplify this a special variation of v4l2_ctrl_cluster was
578introduced:
579
580void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
581 u8 manual_val, bool set_volatile);
582
583The first two arguments are identical to v4l2_ctrl_cluster. The third argument
584tells the framework which value switches the cluster into manual mode. The
Hans Verkuil88365102011-08-26 07:35:14 -0300585last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls.
Hans Verkuil882a9352011-08-26 08:35:59 -0300586If it is false, then the manual controls are never volatile. You would typically
587use that if the hardware does not give you the option to read back to values as
588determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow
589you to obtain the current gain value).
Hans Verkuilc76cd632011-06-07 05:46:53 -0300590
591The first control of the cluster is assumed to be the 'auto' control.
592
593Using this function will ensure that you don't need to handle all the complex
594flag and volatile handling.
595
596
Hans Verkuila42b57f2010-08-01 14:35:53 -0300597VIDIOC_LOG_STATUS Support
598=========================
599
600This ioctl allow you to dump the current status of a driver to the kernel log.
601The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the
602value of the controls owned by the given handler to the log. You can supply a
603prefix as well. If the prefix didn't end with a space, then ': ' will be added
604for you.
605
606
607Different Handlers for Different Video Nodes
608============================================
609
610Usually the V4L2 driver has just one control handler that is global for
611all video nodes. But you can also specify different control handlers for
612different video nodes. You can do that by manually setting the ctrl_handler
613field of struct video_device.
614
615That is no problem if there are no subdevs involved but if there are, then
616you need to block the automatic merging of subdev controls to the global
617control handler. You do that by simply setting the ctrl_handler field in
618struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer
619merge subdev controls.
620
621After each subdev was added, you will then have to call v4l2_ctrl_add_handler
622manually to add the subdev's control handler (sd->ctrl_handler) to the desired
623control handler. This control handler may be specific to the video_device or
624for a subset of video_device's. For example: the radio device nodes only have
625audio controls, while the video and vbi device nodes share the same control
626handler for the audio and video controls.
627
628If you want to have one handler (e.g. for a radio device node) have a subset
629of another handler (e.g. for a video device node), then you should first add
630the controls to the first handler, add the other controls to the second
631handler and finally add the first handler to the second. For example:
632
633 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...);
634 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
635 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
636 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
Hans Verkuil34a6b7d2012-09-14 07:15:03 -0300637 v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler, NULL);
638
639The last argument to v4l2_ctrl_add_handler() is a filter function that allows
640you to filter which controls will be added. Set it to NULL if you want to add
641all controls.
Hans Verkuila42b57f2010-08-01 14:35:53 -0300642
643Or you can add specific controls to a handler:
644
645 volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...);
646 v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...);
647 v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...);
648 v4l2_ctrl_add_ctrl(&radio_ctrl_handler, volume);
649
650What you should not do is make two identical controls for two handlers.
651For example:
652
653 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
654 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...);
655
656This would be bad since muting the radio would not change the video mute
657control. The rule is to have one control for each hardware 'knob' that you
658can twiddle.
659
660
661Finding Controls
662================
663
664Normally you have created the controls yourself and you can store the struct
665v4l2_ctrl pointer into your own struct.
666
667But sometimes you need to find a control from another handler that you do
668not own. For example, if you have to find a volume control from a subdev.
669
670You can do that by calling v4l2_ctrl_find:
671
672 struct v4l2_ctrl *volume;
673
674 volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME);
675
676Since v4l2_ctrl_find will lock the handler you have to be careful where you
677use it. For example, this is not a good idea:
678
679 struct v4l2_ctrl_handler ctrl_handler;
680
681 v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
682 v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
683
684...and in video_ops.s_ctrl:
685
686 case V4L2_CID_BRIGHTNESS:
687 contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST);
688 ...
689
690When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so
691attempting to find another control from the same handler will deadlock.
692
693It is recommended not to use this function from inside the control ops.
694
695
696Inheriting Controls
697===================
698
699When one control handler is added to another using v4l2_ctrl_add_handler, then
700by default all controls from one are merged to the other. But a subdev might
701have low-level controls that make sense for some advanced embedded system, but
702not when it is used in consumer-level hardware. In that case you want to keep
703those low-level controls local to the subdev. You can do this by simply
704setting the 'is_private' flag of the control to 1:
705
706 static const struct v4l2_ctrl_config ctrl_private = {
707 .ops = &ctrl_custom_ops,
708 .id = V4L2_CID_...,
709 .name = "Some Private Control",
710 .type = V4L2_CTRL_TYPE_INTEGER,
711 .max = 15,
712 .step = 1,
713 .is_private = 1,
714 };
715
716 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL);
717
718These controls will now be skipped when v4l2_ctrl_add_handler is called.
719
720
721V4L2_CTRL_TYPE_CTRL_CLASS Controls
722==================================
723
724Controls of this type can be used by GUIs to get the name of the control class.
725A fully featured GUI can make a dialog with multiple tabs with each tab
726containing the controls belonging to a particular control class. The name of
727each tab can be found by querying a special control with ID <control class | 1>.
728
729Drivers do not have to care about this. The framework will automatically add
730a control of this type whenever the first control belonging to a new control
731class is added.
732
733
Hans Verkuil8ac7a942012-09-07 04:46:39 -0300734Adding Notify Callbacks
735=======================
Hans Verkuila42b57f2010-08-01 14:35:53 -0300736
Hans Verkuil8ac7a942012-09-07 04:46:39 -0300737Sometimes the platform or bridge driver needs to be notified when a control
738from a sub-device driver changes. You can set a notify callback by calling
739this function:
Hans Verkuila42b57f2010-08-01 14:35:53 -0300740
Hans Verkuil8ac7a942012-09-07 04:46:39 -0300741void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl,
742 void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv);
Hans Verkuila42b57f2010-08-01 14:35:53 -0300743
Hans Verkuil8ac7a942012-09-07 04:46:39 -0300744Whenever the give control changes value the notify callback will be called
745with a pointer to the control and the priv pointer that was passed with
746v4l2_ctrl_notify. Note that the control's handler lock is held when the
747notify function is called.
748
749There can be only one notify function per control handler. Any attempt
750to set another notify function will cause a WARN_ON.