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