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