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