824 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3V4L2 Controls4=============5 6Introduction7------------8 9The V4L2 control API seems simple enough, but quickly becomes very hard to10implement correctly in drivers. But much of the code needed to handle controls11is actually not driver specific and can be moved to the V4L core framework.12 13After all, the only part that a driver developer is interested in is:14 151) How do I add a control?162) How do I set the control's value? (i.e. s_ctrl)17 18And occasionally:19 203) How do I get the control's value? (i.e. g_volatile_ctrl)214) How do I validate the user's proposed control value? (i.e. try_ctrl)22 23All the rest is something that can be done centrally.24 25The control framework was created in order to implement all the rules of the26V4L2 specification with respect to controls in a central place. And to make27life as easy as possible for the driver developer.28 29Note that the control framework relies on the presence of a struct30:c:type:`v4l2_device` for V4L2 drivers and struct v4l2_subdev for31sub-device drivers.32 33 34Objects in the framework35------------------------36 37There are two main objects:38 39The :c:type:`v4l2_ctrl` object describes the control properties and keeps40track of the control's value (both the current value and the proposed new41value).42 43:c:type:`v4l2_ctrl_handler` is the object that keeps track of controls. It44maintains a list of v4l2_ctrl objects that it owns and another list of45references to controls, possibly to controls owned by other handlers.46 47 48Basic usage for V4L2 and sub-device drivers49-------------------------------------------50 511) Prepare the driver:52 53.. code-block:: c54 55 #include <media/v4l2-ctrls.h>56 571.1) Add the handler to your driver's top-level struct:58 59For V4L2 drivers:60 61.. code-block:: c62 63 struct foo_dev {64 ...65 struct v4l2_device v4l2_dev;66 ...67 struct v4l2_ctrl_handler ctrl_handler;68 ...69 };70 71For sub-device drivers:72 73.. code-block:: c74 75 struct foo_dev {76 ...77 struct v4l2_subdev sd;78 ...79 struct v4l2_ctrl_handler ctrl_handler;80 ...81 };82 831.2) Initialize the handler:84 85.. code-block:: c86 87 v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);88 89The second argument is a hint telling the function how many controls this90handler is expected to handle. It will allocate a hashtable based on this91information. It is a hint only.92 931.3) Hook the control handler into the driver:94 95For V4L2 drivers:96 97.. code-block:: c98 99 foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;100 101For sub-device drivers:102 103.. code-block:: c104 105 foo->sd.ctrl_handler = &foo->ctrl_handler;106 1071.4) Clean up the handler at the end:108 109.. code-block:: c110 111 v4l2_ctrl_handler_free(&foo->ctrl_handler);112 113 1142) Add controls:115 116You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`:117 118.. code-block:: c119 120 struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,121 const struct v4l2_ctrl_ops *ops,122 u32 id, s32 min, s32 max, u32 step, s32 def);123 124Menu and integer menu controls are added by calling125:c:func:`v4l2_ctrl_new_std_menu`:126 127.. code-block:: c128 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 133Menu controls with a driver specific menu are added by calling134:c:func:`v4l2_ctrl_new_std_menu_items`:135 136.. code-block:: c137 138 struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(139 struct v4l2_ctrl_handler *hdl,140 const struct v4l2_ctrl_ops *ops, u32 id, s32 max,141 s32 skip_mask, s32 def, const char * const *qmenu);142 143Standard compound controls can be added by calling144:c:func:`v4l2_ctrl_new_std_compound`:145 146.. code-block:: c147 148 struct v4l2_ctrl *v4l2_ctrl_new_std_compound(struct v4l2_ctrl_handler *hdl,149 const struct v4l2_ctrl_ops *ops, u32 id,150 const union v4l2_ctrl_ptr p_def);151 152Integer menu controls with a driver specific menu can be added by calling153:c:func:`v4l2_ctrl_new_int_menu`:154 155.. code-block:: c156 157 struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,158 const struct v4l2_ctrl_ops *ops,159 u32 id, s32 max, s32 def, const s64 *qmenu_int);160 161These functions are typically called right after the162:c:func:`v4l2_ctrl_handler_init`:163 164.. code-block:: c165 166 static const s64 exp_bias_qmenu[] = {167 -2, -1, 0, 1, 2168 };169 static const char * const test_pattern[] = {170 "Disabled",171 "Vertical Bars",172 "Solid Black",173 "Solid White",174 };175 176 v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);177 v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,178 V4L2_CID_BRIGHTNESS, 0, 255, 1, 128);179 v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,180 V4L2_CID_CONTRAST, 0, 255, 1, 128);181 v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops,182 V4L2_CID_POWER_LINE_FREQUENCY,183 V4L2_CID_POWER_LINE_FREQUENCY_60HZ, 0,184 V4L2_CID_POWER_LINE_FREQUENCY_DISABLED);185 v4l2_ctrl_new_int_menu(&foo->ctrl_handler, &foo_ctrl_ops,186 V4L2_CID_EXPOSURE_BIAS,187 ARRAY_SIZE(exp_bias_qmenu) - 1,188 ARRAY_SIZE(exp_bias_qmenu) / 2 - 1,189 exp_bias_qmenu);190 v4l2_ctrl_new_std_menu_items(&foo->ctrl_handler, &foo_ctrl_ops,191 V4L2_CID_TEST_PATTERN, ARRAY_SIZE(test_pattern) - 1, 0,192 0, test_pattern);193 ...194 if (foo->ctrl_handler.error) {195 int err = foo->ctrl_handler.error;196 197 v4l2_ctrl_handler_free(&foo->ctrl_handler);198 return err;199 }200 201The :c:func:`v4l2_ctrl_new_std` function returns the v4l2_ctrl pointer to202the new control, but if you do not need to access the pointer outside the203control ops, then there is no need to store it.204 205The :c:func:`v4l2_ctrl_new_std` function will fill in most fields based on206the control ID except for the min, max, step and default values. These are207passed in the last four arguments. These values are driver specific while208control attributes like type, name, flags are all global. The control's209current value will be set to the default value.210 211The :c:func:`v4l2_ctrl_new_std_menu` function is very similar but it is212used for menu controls. There is no min argument since that is always 0 for213menu controls, and instead of a step there is a skip_mask argument: if bit214X is 1, then menu item X is skipped.215 216The :c:func:`v4l2_ctrl_new_int_menu` function creates a new standard217integer menu control with driver-specific items in the menu. It differs218from v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and219takes as the last argument an array of signed 64-bit integers that form an220exact menu item list.221 222The :c:func:`v4l2_ctrl_new_std_menu_items` function is very similar to223v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the224driver specific menu for an otherwise standard menu control. A good example225for this control is the test pattern control for capture/display/sensors226devices that have the capability to generate test patterns. These test227patterns are hardware specific, so the contents of the menu will vary from228device to device.229 230Note that if something fails, the function will return NULL or an error and231set ctrl_handler->error to the error code. If ctrl_handler->error was already232set, then it will just return and do nothing. This is also true for233v4l2_ctrl_handler_init if it cannot allocate the internal data structure.234 235This makes it easy to init the handler and just add all controls and only check236the error code at the end. Saves a lot of repetitive error checking.237 238It is recommended to add controls in ascending control ID order: it will be239a bit faster that way.240 2413) Optionally force initial control setup:242 243.. code-block:: c244 245 v4l2_ctrl_handler_setup(&foo->ctrl_handler);246 247This will call s_ctrl for all controls unconditionally. Effectively this248initializes the hardware to the default control values. It is recommended249that you do this as this ensures that both the internal data structures and250the hardware are in sync.251 2524) Finally: implement the :c:type:`v4l2_ctrl_ops`253 254.. code-block:: c255 256 static const struct v4l2_ctrl_ops foo_ctrl_ops = {257 .s_ctrl = foo_s_ctrl,258 };259 260Usually all you need is s_ctrl:261 262.. code-block:: c263 264 static int foo_s_ctrl(struct v4l2_ctrl *ctrl)265 {266 struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);267 268 switch (ctrl->id) {269 case V4L2_CID_BRIGHTNESS:270 write_reg(0x123, ctrl->val);271 break;272 case V4L2_CID_CONTRAST:273 write_reg(0x456, ctrl->val);274 break;275 }276 return 0;277 }278 279The control ops are called with the v4l2_ctrl pointer as argument.280The new control value has already been validated, so all you need to do is281to actually update the hardware registers.282 283You're done! And this is sufficient for most of the drivers we have. No need284to do any validation of control values, or implement QUERYCTRL, QUERY_EXT_CTRL285and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported.286 287 288.. note::289 290 The remainder sections deal with more advanced controls topics and scenarios.291 In practice the basic usage as described above is sufficient for most drivers.292 293 294Inheriting Sub-device Controls295------------------------------296 297When a sub-device is registered with a V4L2 driver by calling298v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev299and v4l2_device are set, then the controls of the subdev will become300automatically available in the V4L2 driver as well. If the subdev driver301contains controls that already exist in the V4L2 driver, then those will be302skipped (so a V4L2 driver can always override a subdev control).303 304What happens here is that v4l2_device_register_subdev() calls305v4l2_ctrl_add_handler() adding the controls of the subdev to the controls306of v4l2_device.307 308 309Accessing Control Values310------------------------311 312The following union is used inside the control framework to access control313values:314 315.. code-block:: c316 317 union v4l2_ctrl_ptr {318 s32 *p_s32;319 s64 *p_s64;320 char *p_char;321 void *p;322 };323 324The v4l2_ctrl struct contains these fields that can be used to access both325current and new values:326 327.. code-block:: c328 329 s32 val;330 struct {331 s32 val;332 } cur;333 334 335 union v4l2_ctrl_ptr p_new;336 union v4l2_ctrl_ptr p_cur;337 338If the control has a simple s32 type, then:339 340.. code-block:: c341 342 &ctrl->val == ctrl->p_new.p_s32343 &ctrl->cur.val == ctrl->p_cur.p_s32344 345For all other types use ctrl->p_cur.p<something>. Basically the val346and cur.val fields can be considered an alias since these are used so often.347 348Within the control ops you can freely use these. The val and cur.val speak for349themselves. The p_char pointers point to character buffers of length350ctrl->maximum + 1, and are always 0-terminated.351 352Unless the control is marked volatile the p_cur field points to the353current cached control value. When you create a new control this value is made354identical to the default value. After calling v4l2_ctrl_handler_setup() this355value is passed to the hardware. It is generally a good idea to call this356function.357 358Whenever a new value is set that new value is automatically cached. This means359that most drivers do not need to implement the g_volatile_ctrl() op. The360exception is for controls that return a volatile register such as a signal361strength read-out that changes continuously. In that case you will need to362implement g_volatile_ctrl like this:363 364.. code-block:: c365 366 static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl)367 {368 switch (ctrl->id) {369 case V4L2_CID_BRIGHTNESS:370 ctrl->val = read_reg(0x123);371 break;372 }373 }374 375Note that you use the 'new value' union as well in g_volatile_ctrl. In general376controls that need to implement g_volatile_ctrl are read-only controls. If they377are not, a V4L2_EVENT_CTRL_CH_VALUE will not be generated when the control378changes.379 380To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:381 382.. code-block:: c383 384 ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);385 if (ctrl)386 ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;387 388For try/s_ctrl the new values (i.e. as passed by the user) are filled in and389you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union390contains the current value, which you can use (but not change!) as well.391 392If s_ctrl returns 0 (OK), then the control framework will copy the new final393values to the 'cur' union.394 395While in g_volatile/s/try_ctrl you can access the value of all controls owned396by the same handler since the handler's lock is held. If you need to access397the value of controls owned by other handlers, then you have to be very careful398not to introduce deadlocks.399 400Outside of the control ops you have to go through to helper functions to get401or set a single control value safely in your driver:402 403.. code-block:: c404 405 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);406 int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);407 408These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls409do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that410will result in a deadlock since these helpers lock the handler as well.411 412You can also take the handler lock yourself:413 414.. code-block:: c415 416 mutex_lock(&state->ctrl_handler.lock);417 pr_info("String value is '%s'\n", ctrl1->p_cur.p_char);418 pr_info("Integer value is '%s'\n", ctrl2->cur.val);419 mutex_unlock(&state->ctrl_handler.lock);420 421 422Menu Controls423-------------424 425The v4l2_ctrl struct contains this union:426 427.. code-block:: c428 429 union {430 u32 step;431 u32 menu_skip_mask;432 };433 434For menu controls menu_skip_mask is used. What it does is that it allows you435to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU436implementation where you can return -EINVAL if a certain menu item is not437present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for438menu controls.439 440A good example is the MPEG Audio Layer II Bitrate menu control where the441menu is a list of standardized possible bitrates. But in practice hardware442implementations will only support a subset of those. By setting the skip443mask you can tell the framework which menu items should be skipped. Setting444it to 0 means that all menu items are supported.445 446You set this mask either through the v4l2_ctrl_config struct for a custom447control, or by calling v4l2_ctrl_new_std_menu().448 449 450Custom Controls451---------------452 453Driver specific controls can be created using v4l2_ctrl_new_custom():454 455.. code-block:: c456 457 static const struct v4l2_ctrl_config ctrl_filter = {458 .ops = &ctrl_custom_ops,459 .id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER,460 .name = "Spatial Filter",461 .type = V4L2_CTRL_TYPE_INTEGER,462 .flags = V4L2_CTRL_FLAG_SLIDER,463 .max = 15,464 .step = 1,465 };466 467 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL);468 469The last argument is the priv pointer which can be set to driver-specific470private data.471 472The v4l2_ctrl_config struct also has a field to set the is_private flag.473 474If the name field is not set, then the framework will assume this is a standard475control and will fill in the name, type and flags fields accordingly.476 477 478Active and Grabbed Controls479---------------------------480 481If you get more complex relationships between controls, then you may have to482activate and deactivate controls. For example, if the Chroma AGC control is483on, then the Chroma Gain control is inactive. That is, you may set it, but484the value will not be used by the hardware as long as the automatic gain485control is on. Typically user interfaces can disable such input fields.486 487You can set the 'active' status using v4l2_ctrl_activate(). By default all488controls are active. Note that the framework does not check for this flag.489It is meant purely for GUIs. The function is typically called from within490s_ctrl.491 492The other flag is the 'grabbed' flag. A grabbed control means that you cannot493change it because it is in use by some resource. Typical examples are MPEG494bitrate controls that cannot be changed while capturing is in progress.495 496If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework497will return -EBUSY if an attempt is made to set this control. The498v4l2_ctrl_grab() function is typically called from the driver when it499starts or stops streaming.500 501 502Control Clusters503----------------504 505By default all controls are independent from the others. But in more506complex scenarios you can get dependencies from one control to another.507In that case you need to 'cluster' them:508 509.. code-block:: c510 511 struct foo {512 struct v4l2_ctrl_handler ctrl_handler;513 #define AUDIO_CL_VOLUME (0)514 #define AUDIO_CL_MUTE (1)515 struct v4l2_ctrl *audio_cluster[2];516 ...517 };518 519 state->audio_cluster[AUDIO_CL_VOLUME] =520 v4l2_ctrl_new_std(&state->ctrl_handler, ...);521 state->audio_cluster[AUDIO_CL_MUTE] =522 v4l2_ctrl_new_std(&state->ctrl_handler, ...);523 v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster);524 525From now on whenever one or more of the controls belonging to the same526cluster is set (or 'gotten', or 'tried'), only the control ops of the first527control ('volume' in this example) is called. You effectively create a new528composite control. Similar to how a 'struct' works in C.529 530So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set531all two controls belonging to the audio_cluster:532 533.. code-block:: c534 535 static int foo_s_ctrl(struct v4l2_ctrl *ctrl)536 {537 struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);538 539 switch (ctrl->id) {540 case V4L2_CID_AUDIO_VOLUME: {541 struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE];542 543 write_reg(0x123, mute->val ? 0 : ctrl->val);544 break;545 }546 case V4L2_CID_CONTRAST:547 write_reg(0x456, ctrl->val);548 break;549 }550 return 0;551 }552 553In the example above the following are equivalent for the VOLUME case:554 555.. code-block:: c556 557 ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]558 ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]559 560In practice using cluster arrays like this becomes very tiresome. So instead561the following equivalent method is used:562 563.. code-block:: c564 565 struct {566 /* audio cluster */567 struct v4l2_ctrl *volume;568 struct v4l2_ctrl *mute;569 };570 571The anonymous struct is used to clearly 'cluster' these two control pointers,572but it serves no other purpose. The effect is the same as creating an573array with two control pointers. So you can just do:574 575.. code-block:: c576 577 state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);578 state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);579 v4l2_ctrl_cluster(2, &state->volume);580 581And in foo_s_ctrl you can use these pointers directly: state->mute->val.582 583Note that controls in a cluster may be NULL. For example, if for some584reason mute was never added (because the hardware doesn't support that585particular feature), then mute will be NULL. So in that case we have a586cluster of 2 controls, of which only 1 is actually instantiated. The587only restriction is that the first control of the cluster must always be588present, since that is the 'master' control of the cluster. The master589control is the one that identifies the cluster and that provides the590pointer to the v4l2_ctrl_ops struct that is used for that cluster.591 592Obviously, all controls in the cluster array must be initialized to either593a valid control or to NULL.594 595In rare cases you might want to know which controls of a cluster actually596were set explicitly by the user. For this you can check the 'is_new' flag of597each control. For example, in the case of a volume/mute cluster the 'is_new'598flag of the mute control would be set if the user called VIDIOC_S_CTRL for599mute only. If the user would call VIDIOC_S_EXT_CTRLS for both mute and volume600controls, then the 'is_new' flag would be 1 for both controls.601 602The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup().603 604 605Handling autogain/gain-type Controls with Auto Clusters606-------------------------------------------------------607 608A common type of control cluster is one that handles 'auto-foo/foo'-type609controls. Typical examples are autogain/gain, autoexposure/exposure,610autowhitebalance/red balance/blue balance. In all cases you have one control611that determines whether another control is handled automatically by the hardware,612or whether it is under manual control from the user.613 614If the cluster is in automatic mode, then the manual controls should be615marked inactive and volatile. When the volatile controls are read the616g_volatile_ctrl operation should return the value that the hardware's automatic617mode set up automatically.618 619If the cluster is put in manual mode, then the manual controls should become620active again and the volatile flag is cleared (so g_volatile_ctrl is no longer621called while in manual mode). In addition just before switching to manual mode622the current values as determined by the auto mode are copied as the new manual623values.624 625Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since626changing that control affects the control flags of the manual controls.627 628In order to simplify this a special variation of v4l2_ctrl_cluster was629introduced:630 631.. code-block:: c632 633 void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,634 u8 manual_val, bool set_volatile);635 636The first two arguments are identical to v4l2_ctrl_cluster. The third argument637tells the framework which value switches the cluster into manual mode. The638last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls.639If it is false, then the manual controls are never volatile. You would typically640use that if the hardware does not give you the option to read back to values as641determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow642you to obtain the current gain value).643 644The first control of the cluster is assumed to be the 'auto' control.645 646Using this function will ensure that you don't need to handle all the complex647flag and volatile handling.648 649 650VIDIOC_LOG_STATUS Support651-------------------------652 653This ioctl allow you to dump the current status of a driver to the kernel log.654The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the655value of the controls owned by the given handler to the log. You can supply a656prefix as well. If the prefix didn't end with a space, then ': ' will be added657for you.658 659 660Different Handlers for Different Video Nodes661--------------------------------------------662 663Usually the V4L2 driver has just one control handler that is global for664all video nodes. But you can also specify different control handlers for665different video nodes. You can do that by manually setting the ctrl_handler666field of struct video_device.667 668That is no problem if there are no subdevs involved but if there are, then669you need to block the automatic merging of subdev controls to the global670control handler. You do that by simply setting the ctrl_handler field in671struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer672merge subdev controls.673 674After each subdev was added, you will then have to call v4l2_ctrl_add_handler675manually to add the subdev's control handler (sd->ctrl_handler) to the desired676control handler. This control handler may be specific to the video_device or677for a subset of video_device's. For example: the radio device nodes only have678audio controls, while the video and vbi device nodes share the same control679handler for the audio and video controls.680 681If you want to have one handler (e.g. for a radio device node) have a subset682of another handler (e.g. for a video device node), then you should first add683the controls to the first handler, add the other controls to the second684handler and finally add the first handler to the second. For example:685 686.. code-block:: c687 688 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...);689 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);690 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);691 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);692 v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler, NULL);693 694The last argument to v4l2_ctrl_add_handler() is a filter function that allows695you to filter which controls will be added. Set it to NULL if you want to add696all controls.697 698Or you can add specific controls to a handler:699 700.. code-block:: c701 702 volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...);703 v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...);704 v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...);705 706What you should not do is make two identical controls for two handlers.707For example:708 709.. code-block:: c710 711 v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);712 v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...);713 714This would be bad since muting the radio would not change the video mute715control. The rule is to have one control for each hardware 'knob' that you716can twiddle.717 718 719Finding Controls720----------------721 722Normally you have created the controls yourself and you can store the struct723v4l2_ctrl pointer into your own struct.724 725But sometimes you need to find a control from another handler that you do726not own. For example, if you have to find a volume control from a subdev.727 728You can do that by calling v4l2_ctrl_find:729 730.. code-block:: c731 732 struct v4l2_ctrl *volume;733 734 volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME);735 736Since v4l2_ctrl_find will lock the handler you have to be careful where you737use it. For example, this is not a good idea:738 739.. code-block:: c740 741 struct v4l2_ctrl_handler ctrl_handler;742 743 v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);744 v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);745 746...and in video_ops.s_ctrl:747 748.. code-block:: c749 750 case V4L2_CID_BRIGHTNESS:751 contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST);752 ...753 754When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so755attempting to find another control from the same handler will deadlock.756 757It is recommended not to use this function from inside the control ops.758 759 760Preventing Controls inheritance761-------------------------------762 763When one control handler is added to another using v4l2_ctrl_add_handler, then764by default all controls from one are merged to the other. But a subdev might765have low-level controls that make sense for some advanced embedded system, but766not when it is used in consumer-level hardware. In that case you want to keep767those low-level controls local to the subdev. You can do this by simply768setting the 'is_private' flag of the control to 1:769 770.. code-block:: c771 772 static const struct v4l2_ctrl_config ctrl_private = {773 .ops = &ctrl_custom_ops,774 .id = V4L2_CID_...,775 .name = "Some Private Control",776 .type = V4L2_CTRL_TYPE_INTEGER,777 .max = 15,778 .step = 1,779 .is_private = 1,780 };781 782 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL);783 784These controls will now be skipped when v4l2_ctrl_add_handler is called.785 786 787V4L2_CTRL_TYPE_CTRL_CLASS Controls788----------------------------------789 790Controls of this type can be used by GUIs to get the name of the control class.791A fully featured GUI can make a dialog with multiple tabs with each tab792containing the controls belonging to a particular control class. The name of793each tab can be found by querying a special control with ID <control class | 1>.794 795Drivers do not have to care about this. The framework will automatically add796a control of this type whenever the first control belonging to a new control797class is added.798 799 800Adding Notify Callbacks801-----------------------802 803Sometimes the platform or bridge driver needs to be notified when a control804from a sub-device driver changes. You can set a notify callback by calling805this function:806 807.. code-block:: c808 809 void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl,810 void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv);811 812Whenever the give control changes value the notify callback will be called813with a pointer to the control and the priv pointer that was passed with814v4l2_ctrl_notify. Note that the control's handler lock is held when the815notify function is called.816 817There can be only one notify function per control handler. Any attempt818to set another notify function will cause a WARN_ON.819 820v4l2_ctrl functions and data structures821---------------------------------------822 823.. kernel-doc:: include/media/v4l2-ctrls.h824