Debian Codegraph @

Documentation/driver-api/media/v4l2-controls.rst

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