blob: cfe52c798d743b0979a31c414948a5c72c491e46 [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
80 Finally, remove all control functions from your v4l2_ioctl_ops:
81 vidioc_queryctrl, vidioc_querymenu, vidioc_g_ctrl, vidioc_s_ctrl,
82 vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls.
83 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
127Menu 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
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300133Or alternatively for integer menu controls, by calling v4l2_ctrl_new_int_menu:
134
135 struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
136 const struct v4l2_ctrl_ops *ops,
137 u32 id, s32 max, s32 def, const s64 *qmenu_int);
138
Lad, Prabhakar117a7112012-09-18 15:54:38 -0300139Standard menu controls with a driver specific menu are added by calling
140v4l2_ctrl_new_std_menu_items:
141
142 struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(
143 struct v4l2_ctrl_handler *hdl,
144 const struct v4l2_ctrl_ops *ops, u32 id, s32 max,
145 s32 skip_mask, s32 def, const char * const *qmenu);
146
Hans Verkuila42b57f2010-08-01 14:35:53 -0300147These functions are typically called right after the v4l2_ctrl_handler_init:
148
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300149 static const s64 exp_bias_qmenu[] = {
150 -2, -1, 0, 1, 2
151 };
Lad, Prabhakar117a7112012-09-18 15:54:38 -0300152 static const char * const test_pattern[] = {
153 "Disabled",
154 "Vertical Bars",
155 "Solid Black",
156 "Solid White",
157 };
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300158
Hans Verkuila42b57f2010-08-01 14:35:53 -0300159 v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
160 v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
161 V4L2_CID_BRIGHTNESS, 0, 255, 1, 128);
162 v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
163 V4L2_CID_CONTRAST, 0, 255, 1, 128);
164 v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops,
165 V4L2_CID_POWER_LINE_FREQUENCY,
166 V4L2_CID_POWER_LINE_FREQUENCY_60HZ, 0,
167 V4L2_CID_POWER_LINE_FREQUENCY_DISABLED);
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300168 v4l2_ctrl_new_int_menu(&foo->ctrl_handler, &foo_ctrl_ops,
169 V4L2_CID_EXPOSURE_BIAS,
170 ARRAY_SIZE(exp_bias_qmenu) - 1,
171 ARRAY_SIZE(exp_bias_qmenu) / 2 - 1,
172 exp_bias_qmenu);
Lad, Prabhakar117a7112012-09-18 15:54:38 -0300173 v4l2_ctrl_new_std_menu_items(&foo->ctrl_handler, &foo_ctrl_ops,
174 V4L2_CID_TEST_PATTERN, ARRAY_SIZE(test_pattern) - 1, 0,
175 0, test_pattern);
Hans Verkuila42b57f2010-08-01 14:35:53 -0300176 ...
177 if (foo->ctrl_handler.error) {
178 int err = foo->ctrl_handler.error;
179
180 v4l2_ctrl_handler_free(&foo->ctrl_handler);
181 return err;
182 }
183
184The v4l2_ctrl_new_std function returns the v4l2_ctrl pointer to the new
185control, but if you do not need to access the pointer outside the control ops,
186then there is no need to store it.
187
188The v4l2_ctrl_new_std function will fill in most fields based on the control
189ID except for the min, max, step and default values. These are passed in the
190last four arguments. These values are driver specific while control attributes
191like type, name, flags are all global. The control's current value will be set
192to the default value.
193
194The v4l2_ctrl_new_std_menu function is very similar but it is used for menu
195controls. There is no min argument since that is always 0 for menu controls,
196and instead of a step there is a skip_mask argument: if bit X is 1, then menu
197item X is skipped.
198
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300199The v4l2_ctrl_new_int_menu function creates a new standard integer menu
200control with driver-specific items in the menu. It differs from
201v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and takes
202as the last argument an array of signed 64-bit integers that form an exact
203menu item list.
204
Lad, Prabhakar117a7112012-09-18 15:54:38 -0300205The v4l2_ctrl_new_std_menu_items function is very similar to
206v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the driver
207specific menu for an otherwise standard menu control. A good example for this
208control is the test pattern control for capture/display/sensors devices that
209have the capability to generate test patterns. These test patterns are hardware
210specific, so the contents of the menu will vary from device to device.
211
Hans Verkuila42b57f2010-08-01 14:35:53 -0300212Note that if something fails, the function will return NULL or an error and
213set ctrl_handler->error to the error code. If ctrl_handler->error was already
214set, then it will just return and do nothing. This is also true for
215v4l2_ctrl_handler_init if it cannot allocate the internal data structure.
216
217This makes it easy to init the handler and just add all controls and only check
218the error code at the end. Saves a lot of repetitive error checking.
219
220It is recommended to add controls in ascending control ID order: it will be
221a bit faster that way.
222
2233) Optionally force initial control setup:
224
225 v4l2_ctrl_handler_setup(&foo->ctrl_handler);
226
227This will call s_ctrl for all controls unconditionally. Effectively this
228initializes the hardware to the default control values. It is recommended
229that you do this as this ensures that both the internal data structures and
230the hardware are in sync.
231
2324) Finally: implement the v4l2_ctrl_ops
233
234 static const struct v4l2_ctrl_ops foo_ctrl_ops = {
235 .s_ctrl = foo_s_ctrl,
236 };
237
238Usually all you need is s_ctrl:
239
240 static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
241 {
242 struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
243
244 switch (ctrl->id) {
245 case V4L2_CID_BRIGHTNESS:
246 write_reg(0x123, ctrl->val);
247 break;
248 case V4L2_CID_CONTRAST:
249 write_reg(0x456, ctrl->val);
250 break;
251 }
252 return 0;
253 }
254
255The control ops are called with the v4l2_ctrl pointer as argument.
256The new control value has already been validated, so all you need to do is
257to actually update the hardware registers.
258
259You're done! And this is sufficient for most of the drivers we have. No need
260to do any validation of control values, or implement QUERYCTRL/QUERYMENU. And
261G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported.
262
263
264==============================================================================
265
266The remainder of this document deals with more advanced topics and scenarios.
267In practice the basic usage as described above is sufficient for most drivers.
268
269===============================================================================
270
271
272Inheriting Controls
273===================
274
275When a sub-device is registered with a V4L2 driver by calling
276v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev
277and v4l2_device are set, then the controls of the subdev will become
278automatically available in the V4L2 driver as well. If the subdev driver
279contains controls that already exist in the V4L2 driver, then those will be
280skipped (so a V4L2 driver can always override a subdev control).
281
282What happens here is that v4l2_device_register_subdev() calls
283v4l2_ctrl_add_handler() adding the controls of the subdev to the controls
284of v4l2_device.
285
286
287Accessing Control Values
288========================
289
290The v4l2_ctrl struct contains these two unions:
291
292 /* The current control value. */
293 union {
294 s32 val;
295 s64 val64;
296 char *string;
297 } cur;
298
299 /* The new control value. */
300 union {
301 s32 val;
302 s64 val64;
303 char *string;
304 };
305
306Within the control ops you can freely use these. The val and val64 speak for
307themselves. The string pointers point to character buffers of length
308ctrl->maximum + 1, and are always 0-terminated.
309
310In most cases 'cur' contains the current cached control value. When you create
311a new control this value is made identical to the default value. After calling
312v4l2_ctrl_handler_setup() this value is passed to the hardware. It is generally
313a good idea to call this function.
314
315Whenever a new value is set that new value is automatically cached. This means
316that most drivers do not need to implement the g_volatile_ctrl() op. The
317exception is for controls that return a volatile register such as a signal
318strength read-out that changes continuously. In that case you will need to
319implement g_volatile_ctrl like this:
320
321 static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl)
322 {
323 switch (ctrl->id) {
324 case V4L2_CID_BRIGHTNESS:
Hans Verkuil78866ef2011-05-27 08:53:37 -0300325 ctrl->val = read_reg(0x123);
Hans Verkuila42b57f2010-08-01 14:35:53 -0300326 break;
327 }
328 }
329
Hans Verkuil78866ef2011-05-27 08:53:37 -0300330Note that you use the 'new value' union as well in g_volatile_ctrl. In general
331controls that need to implement g_volatile_ctrl are read-only controls.
Hans Verkuil2a863792011-01-11 14:45:03 -0300332
Hans Verkuil88365102011-08-26 07:35:14 -0300333To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:
Hans Verkuila42b57f2010-08-01 14:35:53 -0300334
335 ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);
336 if (ctrl)
Hans Verkuil88365102011-08-26 07:35:14 -0300337 ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;
Hans Verkuila42b57f2010-08-01 14:35:53 -0300338
339For try/s_ctrl the new values (i.e. as passed by the user) are filled in and
340you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union
341contains the current value, which you can use (but not change!) as well.
342
343If s_ctrl returns 0 (OK), then the control framework will copy the new final
344values to the 'cur' union.
345
346While in g_volatile/s/try_ctrl you can access the value of all controls owned
347by the same handler since the handler's lock is held. If you need to access
348the value of controls owned by other handlers, then you have to be very careful
349not to introduce deadlocks.
350
351Outside of the control ops you have to go through to helper functions to get
352or set a single control value safely in your driver:
353
354 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
355 int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
356
357These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls
358do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that
359will result in a deadlock since these helpers lock the handler as well.
360
361You can also take the handler lock yourself:
362
363 mutex_lock(&state->ctrl_handler.lock);
364 printk(KERN_INFO "String value is '%s'\n", ctrl1->cur.string);
365 printk(KERN_INFO "Integer value is '%s'\n", ctrl2->cur.val);
366 mutex_unlock(&state->ctrl_handler.lock);
367
368
369Menu Controls
370=============
371
372The v4l2_ctrl struct contains this union:
373
374 union {
375 u32 step;
376 u32 menu_skip_mask;
377 };
378
379For menu controls menu_skip_mask is used. What it does is that it allows you
380to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU
381implementation where you can return -EINVAL if a certain menu item is not
382present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for
383menu controls.
384
385A good example is the MPEG Audio Layer II Bitrate menu control where the
386menu is a list of standardized possible bitrates. But in practice hardware
387implementations will only support a subset of those. By setting the skip
388mask you can tell the framework which menu items should be skipped. Setting
389it to 0 means that all menu items are supported.
390
391You set this mask either through the v4l2_ctrl_config struct for a custom
392control, or by calling v4l2_ctrl_new_std_menu().
393
394
395Custom Controls
396===============
397
398Driver specific controls can be created using v4l2_ctrl_new_custom():
399
400 static const struct v4l2_ctrl_config ctrl_filter = {
401 .ops = &ctrl_custom_ops,
402 .id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER,
403 .name = "Spatial Filter",
404 .type = V4L2_CTRL_TYPE_INTEGER,
405 .flags = V4L2_CTRL_FLAG_SLIDER,
406 .max = 15,
407 .step = 1,
408 };
409
410 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL);
411
412The last argument is the priv pointer which can be set to driver-specific
413private data.
414
Hans Verkuil88365102011-08-26 07:35:14 -0300415The v4l2_ctrl_config struct also has a field to set the is_private flag.
Hans Verkuila42b57f2010-08-01 14:35:53 -0300416
417If the name field is not set, then the framework will assume this is a standard
418control and will fill in the name, type and flags fields accordingly.
419
420
421Active and Grabbed Controls
422===========================
423
424If you get more complex relationships between controls, then you may have to
425activate and deactivate controls. For example, if the Chroma AGC control is
426on, then the Chroma Gain control is inactive. That is, you may set it, but
427the value will not be used by the hardware as long as the automatic gain
428control is on. Typically user interfaces can disable such input fields.
429
430You can set the 'active' status using v4l2_ctrl_activate(). By default all
431controls are active. Note that the framework does not check for this flag.
432It is meant purely for GUIs. The function is typically called from within
433s_ctrl.
434
435The other flag is the 'grabbed' flag. A grabbed control means that you cannot
436change it because it is in use by some resource. Typical examples are MPEG
437bitrate controls that cannot be changed while capturing is in progress.
438
439If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework
440will return -EBUSY if an attempt is made to set this control. The
441v4l2_ctrl_grab() function is typically called from the driver when it
442starts or stops streaming.
443
444
445Control Clusters
446================
447
448By default all controls are independent from the others. But in more
449complex scenarios you can get dependencies from one control to another.
450In that case you need to 'cluster' them:
451
452 struct foo {
453 struct v4l2_ctrl_handler ctrl_handler;
454#define AUDIO_CL_VOLUME (0)
455#define AUDIO_CL_MUTE (1)
456 struct v4l2_ctrl *audio_cluster[2];
457 ...
458 };
459
460 state->audio_cluster[AUDIO_CL_VOLUME] =
461 v4l2_ctrl_new_std(&state->ctrl_handler, ...);
462 state->audio_cluster[AUDIO_CL_MUTE] =
463 v4l2_ctrl_new_std(&state->ctrl_handler, ...);
464 v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster);
465
466From now on whenever one or more of the controls belonging to the same
467cluster is set (or 'gotten', or 'tried'), only the control ops of the first
468control ('volume' in this example) is called. You effectively create a new
469composite control. Similar to how a 'struct' works in C.
470
471So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set
472all two controls belonging to the audio_cluster:
473
474 static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
475 {
476 struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
477
478 switch (ctrl->id) {
479 case V4L2_CID_AUDIO_VOLUME: {
480 struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE];
481
482 write_reg(0x123, mute->val ? 0 : ctrl->val);
483 break;
484 }
485 case V4L2_CID_CONTRAST:
486 write_reg(0x456, ctrl->val);
487 break;
488 }
489 return 0;
490 }
491
492In the example above the following are equivalent for the VOLUME case:
493
494 ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
495 ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
496
Hans Verkuilc76cd632011-06-07 05:46:53 -0300497In practice using cluster arrays like this becomes very tiresome. So instead
498the following equivalent method is used:
499
500 struct {
501 /* audio cluster */
502 struct v4l2_ctrl *volume;
503 struct v4l2_ctrl *mute;
504 };
505
506The anonymous struct is used to clearly 'cluster' these two control pointers,
507but it serves no other purpose. The effect is the same as creating an
508array with two control pointers. So you can just do:
509
510 state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
511 state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
512 v4l2_ctrl_cluster(2, &state->volume);
513
514And in foo_s_ctrl you can use these pointers directly: state->mute->val.
515
Hans Verkuila42b57f2010-08-01 14:35:53 -0300516Note that controls in a cluster may be NULL. For example, if for some
517reason mute was never added (because the hardware doesn't support that
518particular feature), then mute will be NULL. So in that case we have a
519cluster of 2 controls, of which only 1 is actually instantiated. The
520only restriction is that the first control of the cluster must always be
521present, since that is the 'master' control of the cluster. The master
522control is the one that identifies the cluster and that provides the
523pointer to the v4l2_ctrl_ops struct that is used for that cluster.
524
525Obviously, all controls in the cluster array must be initialized to either
526a valid control or to NULL.
527
Hans Verkuil2a863792011-01-11 14:45:03 -0300528In rare cases you might want to know which controls of a cluster actually
529were set explicitly by the user. For this you can check the 'is_new' flag of
530each control. For example, in the case of a volume/mute cluster the 'is_new'
531flag of the mute control would be set if the user called VIDIOC_S_CTRL for
532mute only. If the user would call VIDIOC_S_EXT_CTRLS for both mute and volume
533controls, then the 'is_new' flag would be 1 for both controls.
534
535The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup().
536
Hans Verkuila42b57f2010-08-01 14:35:53 -0300537
Hans Verkuilc76cd632011-06-07 05:46:53 -0300538Handling autogain/gain-type Controls with Auto Clusters
539=======================================================
540
541A common type of control cluster is one that handles 'auto-foo/foo'-type
542controls. Typical examples are autogain/gain, autoexposure/exposure,
Hans Verkuil882a9352011-08-26 08:35:59 -0300543autowhitebalance/red balance/blue balance. In all cases you have one control
Hans Verkuilc76cd632011-06-07 05:46:53 -0300544that determines whether another control is handled automatically by the hardware,
545or whether it is under manual control from the user.
546
547If the cluster is in automatic mode, then the manual controls should be
Hans Verkuil882a9352011-08-26 08:35:59 -0300548marked inactive and volatile. When the volatile controls are read the
549g_volatile_ctrl operation should return the value that the hardware's automatic
550mode set up automatically.
Hans Verkuilc76cd632011-06-07 05:46:53 -0300551
552If the cluster is put in manual mode, then the manual controls should become
Hans Verkuil882a9352011-08-26 08:35:59 -0300553active again and the volatile flag is cleared (so g_volatile_ctrl is no longer
554called while in manual mode). In addition just before switching to manual mode
555the current values as determined by the auto mode are copied as the new manual
556values.
Hans Verkuilc76cd632011-06-07 05:46:53 -0300557
558Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since
559changing that control affects the control flags of the manual controls.
560
561In order to simplify this a special variation of v4l2_ctrl_cluster was
562introduced:
563
564void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
565 u8 manual_val, bool set_volatile);
566
567The first two arguments are identical to v4l2_ctrl_cluster. The third argument
568tells the framework which value switches the cluster into manual mode. The
Hans Verkuil88365102011-08-26 07:35:14 -0300569last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls.
Hans Verkuil882a9352011-08-26 08:35:59 -0300570If it is false, then the manual controls are never volatile. You would typically
571use that if the hardware does not give you the option to read back to values as
572determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow
573you to obtain the current gain value).
Hans Verkuilc76cd632011-06-07 05:46:53 -0300574
575The first control of the cluster is assumed to be the 'auto' control.
576
577Using this function will ensure that you don't need to handle all the complex
578flag and volatile handling.
579
580
Hans Verkuila42b57f2010-08-01 14:35:53 -0300581VIDIOC_LOG_STATUS Support
582=========================
583
584This ioctl allow you to dump the current status of a driver to the kernel log.
585The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the
586value of the controls owned by the given handler to the log. You can supply a
587prefix as well. If the prefix didn't end with a space, then ': ' will be added
588for you.
589
590
591Different Handlers for Different Video Nodes
592============================================
593
594Usually the V4L2 driver has just one control handler that is global for
595all video nodes. But you can also specify different control handlers for
596different video nodes. You can do that by manually setting the ctrl_handler
597field of struct video_device.
598
599That is no problem if there are no subdevs involved but if there are, then
600you need to block the automatic merging of subdev controls to the global
601control handler. You do that by simply setting the ctrl_handler field in
602struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer
603merge subdev controls.
604
605After each subdev was added, you will then have to call v4l2_ctrl_add_handler
606manually to add the subdev's control handler (sd->ctrl_handler) to the desired
607control handler. This control handler may be specific to the video_device or
608for a subset of video_device's. For example: the radio device nodes only have
609audio controls, while the video and vbi device nodes share the same control
610handler for the audio and video controls.
611
612If you want to have one handler (e.g. for a radio device node) have a subset
613of another handler (e.g. for a video device node), then you should first add
614the controls to the first handler, add the other controls to the second
615handler and finally add the first handler to the second. For example:
616
617 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...);
618 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
619 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
620 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
Hans Verkuil34a6b7d2012-09-14 07:15:03 -0300621 v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler, NULL);
622
623The last argument to v4l2_ctrl_add_handler() is a filter function that allows
624you to filter which controls will be added. Set it to NULL if you want to add
625all controls.
Hans Verkuila42b57f2010-08-01 14:35:53 -0300626
627Or you can add specific controls to a handler:
628
629 volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...);
630 v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...);
631 v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...);
632 v4l2_ctrl_add_ctrl(&radio_ctrl_handler, volume);
633
634What you should not do is make two identical controls for two handlers.
635For example:
636
637 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
638 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...);
639
640This would be bad since muting the radio would not change the video mute
641control. The rule is to have one control for each hardware 'knob' that you
642can twiddle.
643
644
645Finding Controls
646================
647
648Normally you have created the controls yourself and you can store the struct
649v4l2_ctrl pointer into your own struct.
650
651But sometimes you need to find a control from another handler that you do
652not own. For example, if you have to find a volume control from a subdev.
653
654You can do that by calling v4l2_ctrl_find:
655
656 struct v4l2_ctrl *volume;
657
658 volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME);
659
660Since v4l2_ctrl_find will lock the handler you have to be careful where you
661use it. For example, this is not a good idea:
662
663 struct v4l2_ctrl_handler ctrl_handler;
664
665 v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
666 v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
667
668...and in video_ops.s_ctrl:
669
670 case V4L2_CID_BRIGHTNESS:
671 contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST);
672 ...
673
674When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so
675attempting to find another control from the same handler will deadlock.
676
677It is recommended not to use this function from inside the control ops.
678
679
680Inheriting Controls
681===================
682
683When one control handler is added to another using v4l2_ctrl_add_handler, then
684by default all controls from one are merged to the other. But a subdev might
685have low-level controls that make sense for some advanced embedded system, but
686not when it is used in consumer-level hardware. In that case you want to keep
687those low-level controls local to the subdev. You can do this by simply
688setting the 'is_private' flag of the control to 1:
689
690 static const struct v4l2_ctrl_config ctrl_private = {
691 .ops = &ctrl_custom_ops,
692 .id = V4L2_CID_...,
693 .name = "Some Private Control",
694 .type = V4L2_CTRL_TYPE_INTEGER,
695 .max = 15,
696 .step = 1,
697 .is_private = 1,
698 };
699
700 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL);
701
702These controls will now be skipped when v4l2_ctrl_add_handler is called.
703
704
705V4L2_CTRL_TYPE_CTRL_CLASS Controls
706==================================
707
708Controls of this type can be used by GUIs to get the name of the control class.
709A fully featured GUI can make a dialog with multiple tabs with each tab
710containing the controls belonging to a particular control class. The name of
711each tab can be found by querying a special control with ID <control class | 1>.
712
713Drivers do not have to care about this. The framework will automatically add
714a control of this type whenever the first control belonging to a new control
715class is added.
716
717
Hans Verkuila42b57f2010-08-01 14:35:53 -0300718Proposals for Extensions
719========================
720
721Some ideas for future extensions to the spec:
722
7231) Add a V4L2_CTRL_FLAG_HEX to have values shown as hexadecimal instead of
724decimal. Useful for e.g. video_mute_yuv.
725
7262) It is possible to mark in the controls array which controls have been
727successfully written and which failed by for example adding a bit to the
728control ID. Not sure if it is worth the effort, though.