Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 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: |
| 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 | |
| 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 | |
Sylwester Nawrocki | d1e9b7c | 2013-07-09 01:24:40 -0300 | [diff] [blame] | 127 | Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu: |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 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 | |
Sylwester Nawrocki | d1e9b7c | 2013-07-09 01:24:40 -0300 | [diff] [blame] | 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: |
Sylwester Nawrocki | 515f328 | 2012-05-06 15:30:44 -0300 | [diff] [blame] | 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 | |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 148 | These functions are typically called right after the v4l2_ctrl_handler_init: |
| 149 | |
Sylwester Nawrocki | 515f328 | 2012-05-06 15:30:44 -0300 | [diff] [blame] | 150 | static const s64 exp_bias_qmenu[] = { |
| 151 | -2, -1, 0, 1, 2 |
| 152 | }; |
Lad, Prabhakar | 117a711 | 2012-09-18 15:54:38 -0300 | [diff] [blame] | 153 | static const char * const test_pattern[] = { |
| 154 | "Disabled", |
| 155 | "Vertical Bars", |
| 156 | "Solid Black", |
| 157 | "Solid White", |
| 158 | }; |
Sylwester Nawrocki | 515f328 | 2012-05-06 15:30:44 -0300 | [diff] [blame] | 159 | |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 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); |
Sylwester Nawrocki | 515f328 | 2012-05-06 15:30:44 -0300 | [diff] [blame] | 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); |
Lad, Prabhakar | 117a711 | 2012-09-18 15:54:38 -0300 | [diff] [blame] | 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); |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 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 | |
Sylwester Nawrocki | 515f328 | 2012-05-06 15:30:44 -0300 | [diff] [blame] | 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 | |
Lad, Prabhakar | 117a711 | 2012-09-18 15:54:38 -0300 | [diff] [blame] | 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 | |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 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/QUERYMENU. And |
| 262 | 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 v4l2_ctrl struct contains these two unions: |
| 292 | |
| 293 | /* The current control value. */ |
| 294 | union { |
| 295 | s32 val; |
| 296 | s64 val64; |
| 297 | char *string; |
| 298 | } cur; |
| 299 | |
| 300 | /* The new control value. */ |
| 301 | union { |
| 302 | s32 val; |
| 303 | s64 val64; |
| 304 | char *string; |
| 305 | }; |
| 306 | |
| 307 | Within the control ops you can freely use these. The val and val64 speak for |
| 308 | themselves. The string pointers point to character buffers of length |
| 309 | ctrl->maximum + 1, and are always 0-terminated. |
| 310 | |
| 311 | In most cases 'cur' contains the current cached control value. When you create |
| 312 | a new control this value is made identical to the default value. After calling |
| 313 | v4l2_ctrl_handler_setup() this value is passed to the hardware. It is generally |
| 314 | a good idea to call this function. |
| 315 | |
| 316 | Whenever a new value is set that new value is automatically cached. This means |
| 317 | that most drivers do not need to implement the g_volatile_ctrl() op. The |
| 318 | exception is for controls that return a volatile register such as a signal |
| 319 | strength read-out that changes continuously. In that case you will need to |
| 320 | implement g_volatile_ctrl like this: |
| 321 | |
| 322 | static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl) |
| 323 | { |
| 324 | switch (ctrl->id) { |
| 325 | case V4L2_CID_BRIGHTNESS: |
Hans Verkuil | 78866ef | 2011-05-27 08:53:37 -0300 | [diff] [blame] | 326 | ctrl->val = read_reg(0x123); |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 327 | break; |
| 328 | } |
| 329 | } |
| 330 | |
Hans Verkuil | 78866ef | 2011-05-27 08:53:37 -0300 | [diff] [blame] | 331 | Note that you use the 'new value' union as well in g_volatile_ctrl. In general |
| 332 | controls that need to implement g_volatile_ctrl are read-only controls. |
Hans Verkuil | 2a86379 | 2011-01-11 14:45:03 -0300 | [diff] [blame] | 333 | |
Hans Verkuil | 8836510 | 2011-08-26 07:35:14 -0300 | [diff] [blame] | 334 | To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE: |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 335 | |
| 336 | ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...); |
| 337 | if (ctrl) |
Hans Verkuil | 8836510 | 2011-08-26 07:35:14 -0300 | [diff] [blame] | 338 | ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE; |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 339 | |
| 340 | For try/s_ctrl the new values (i.e. as passed by the user) are filled in and |
| 341 | you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union |
| 342 | contains the current value, which you can use (but not change!) as well. |
| 343 | |
| 344 | If s_ctrl returns 0 (OK), then the control framework will copy the new final |
| 345 | values to the 'cur' union. |
| 346 | |
| 347 | While in g_volatile/s/try_ctrl you can access the value of all controls owned |
| 348 | by the same handler since the handler's lock is held. If you need to access |
| 349 | the value of controls owned by other handlers, then you have to be very careful |
| 350 | not to introduce deadlocks. |
| 351 | |
| 352 | Outside of the control ops you have to go through to helper functions to get |
| 353 | or set a single control value safely in your driver: |
| 354 | |
| 355 | s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl); |
| 356 | int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val); |
| 357 | |
| 358 | These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls |
| 359 | do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that |
| 360 | will result in a deadlock since these helpers lock the handler as well. |
| 361 | |
| 362 | You can also take the handler lock yourself: |
| 363 | |
| 364 | mutex_lock(&state->ctrl_handler.lock); |
| 365 | printk(KERN_INFO "String value is '%s'\n", ctrl1->cur.string); |
| 366 | printk(KERN_INFO "Integer value is '%s'\n", ctrl2->cur.val); |
| 367 | mutex_unlock(&state->ctrl_handler.lock); |
| 368 | |
| 369 | |
| 370 | Menu Controls |
| 371 | ============= |
| 372 | |
| 373 | The v4l2_ctrl struct contains this union: |
| 374 | |
| 375 | union { |
| 376 | u32 step; |
| 377 | u32 menu_skip_mask; |
| 378 | }; |
| 379 | |
| 380 | For menu controls menu_skip_mask is used. What it does is that it allows you |
| 381 | to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU |
| 382 | implementation where you can return -EINVAL if a certain menu item is not |
| 383 | present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for |
| 384 | menu controls. |
| 385 | |
| 386 | A good example is the MPEG Audio Layer II Bitrate menu control where the |
| 387 | menu is a list of standardized possible bitrates. But in practice hardware |
| 388 | implementations will only support a subset of those. By setting the skip |
| 389 | mask you can tell the framework which menu items should be skipped. Setting |
| 390 | it to 0 means that all menu items are supported. |
| 391 | |
| 392 | You set this mask either through the v4l2_ctrl_config struct for a custom |
| 393 | control, or by calling v4l2_ctrl_new_std_menu(). |
| 394 | |
| 395 | |
| 396 | Custom Controls |
| 397 | =============== |
| 398 | |
| 399 | Driver specific controls can be created using v4l2_ctrl_new_custom(): |
| 400 | |
| 401 | static const struct v4l2_ctrl_config ctrl_filter = { |
| 402 | .ops = &ctrl_custom_ops, |
| 403 | .id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER, |
| 404 | .name = "Spatial Filter", |
| 405 | .type = V4L2_CTRL_TYPE_INTEGER, |
| 406 | .flags = V4L2_CTRL_FLAG_SLIDER, |
| 407 | .max = 15, |
| 408 | .step = 1, |
| 409 | }; |
| 410 | |
| 411 | ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL); |
| 412 | |
| 413 | The last argument is the priv pointer which can be set to driver-specific |
| 414 | private data. |
| 415 | |
Hans Verkuil | 8836510 | 2011-08-26 07:35:14 -0300 | [diff] [blame] | 416 | The v4l2_ctrl_config struct also has a field to set the is_private flag. |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 417 | |
| 418 | If the name field is not set, then the framework will assume this is a standard |
| 419 | control and will fill in the name, type and flags fields accordingly. |
| 420 | |
| 421 | |
| 422 | Active and Grabbed Controls |
| 423 | =========================== |
| 424 | |
| 425 | If you get more complex relationships between controls, then you may have to |
| 426 | activate and deactivate controls. For example, if the Chroma AGC control is |
| 427 | on, then the Chroma Gain control is inactive. That is, you may set it, but |
| 428 | the value will not be used by the hardware as long as the automatic gain |
| 429 | control is on. Typically user interfaces can disable such input fields. |
| 430 | |
| 431 | You can set the 'active' status using v4l2_ctrl_activate(). By default all |
| 432 | controls are active. Note that the framework does not check for this flag. |
| 433 | It is meant purely for GUIs. The function is typically called from within |
| 434 | s_ctrl. |
| 435 | |
| 436 | The other flag is the 'grabbed' flag. A grabbed control means that you cannot |
| 437 | change it because it is in use by some resource. Typical examples are MPEG |
| 438 | bitrate controls that cannot be changed while capturing is in progress. |
| 439 | |
| 440 | If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework |
| 441 | will return -EBUSY if an attempt is made to set this control. The |
| 442 | v4l2_ctrl_grab() function is typically called from the driver when it |
| 443 | starts or stops streaming. |
| 444 | |
| 445 | |
| 446 | Control Clusters |
| 447 | ================ |
| 448 | |
| 449 | By default all controls are independent from the others. But in more |
| 450 | complex scenarios you can get dependencies from one control to another. |
| 451 | In that case you need to 'cluster' them: |
| 452 | |
| 453 | struct foo { |
| 454 | struct v4l2_ctrl_handler ctrl_handler; |
| 455 | #define AUDIO_CL_VOLUME (0) |
| 456 | #define AUDIO_CL_MUTE (1) |
| 457 | struct v4l2_ctrl *audio_cluster[2]; |
| 458 | ... |
| 459 | }; |
| 460 | |
| 461 | state->audio_cluster[AUDIO_CL_VOLUME] = |
| 462 | v4l2_ctrl_new_std(&state->ctrl_handler, ...); |
| 463 | state->audio_cluster[AUDIO_CL_MUTE] = |
| 464 | v4l2_ctrl_new_std(&state->ctrl_handler, ...); |
| 465 | v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster); |
| 466 | |
| 467 | From now on whenever one or more of the controls belonging to the same |
| 468 | cluster is set (or 'gotten', or 'tried'), only the control ops of the first |
| 469 | control ('volume' in this example) is called. You effectively create a new |
| 470 | composite control. Similar to how a 'struct' works in C. |
| 471 | |
| 472 | So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set |
| 473 | all two controls belonging to the audio_cluster: |
| 474 | |
| 475 | static int foo_s_ctrl(struct v4l2_ctrl *ctrl) |
| 476 | { |
| 477 | struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler); |
| 478 | |
| 479 | switch (ctrl->id) { |
| 480 | case V4L2_CID_AUDIO_VOLUME: { |
| 481 | struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE]; |
| 482 | |
| 483 | write_reg(0x123, mute->val ? 0 : ctrl->val); |
| 484 | break; |
| 485 | } |
| 486 | case V4L2_CID_CONTRAST: |
| 487 | write_reg(0x456, ctrl->val); |
| 488 | break; |
| 489 | } |
| 490 | return 0; |
| 491 | } |
| 492 | |
| 493 | In the example above the following are equivalent for the VOLUME case: |
| 494 | |
| 495 | ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME] |
| 496 | ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE] |
| 497 | |
Hans Verkuil | c76cd63 | 2011-06-07 05:46:53 -0300 | [diff] [blame] | 498 | In practice using cluster arrays like this becomes very tiresome. So instead |
| 499 | the following equivalent method is used: |
| 500 | |
| 501 | struct { |
| 502 | /* audio cluster */ |
| 503 | struct v4l2_ctrl *volume; |
| 504 | struct v4l2_ctrl *mute; |
| 505 | }; |
| 506 | |
| 507 | The anonymous struct is used to clearly 'cluster' these two control pointers, |
| 508 | but it serves no other purpose. The effect is the same as creating an |
| 509 | array with two control pointers. So you can just do: |
| 510 | |
| 511 | state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...); |
| 512 | state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...); |
| 513 | v4l2_ctrl_cluster(2, &state->volume); |
| 514 | |
| 515 | And in foo_s_ctrl you can use these pointers directly: state->mute->val. |
| 516 | |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 517 | Note that controls in a cluster may be NULL. For example, if for some |
| 518 | reason mute was never added (because the hardware doesn't support that |
| 519 | particular feature), then mute will be NULL. So in that case we have a |
| 520 | cluster of 2 controls, of which only 1 is actually instantiated. The |
| 521 | only restriction is that the first control of the cluster must always be |
| 522 | present, since that is the 'master' control of the cluster. The master |
| 523 | control is the one that identifies the cluster and that provides the |
| 524 | pointer to the v4l2_ctrl_ops struct that is used for that cluster. |
| 525 | |
| 526 | Obviously, all controls in the cluster array must be initialized to either |
| 527 | a valid control or to NULL. |
| 528 | |
Hans Verkuil | 2a86379 | 2011-01-11 14:45:03 -0300 | [diff] [blame] | 529 | In rare cases you might want to know which controls of a cluster actually |
| 530 | were set explicitly by the user. For this you can check the 'is_new' flag of |
| 531 | each control. For example, in the case of a volume/mute cluster the 'is_new' |
| 532 | flag of the mute control would be set if the user called VIDIOC_S_CTRL for |
| 533 | mute only. If the user would call VIDIOC_S_EXT_CTRLS for both mute and volume |
| 534 | controls, then the 'is_new' flag would be 1 for both controls. |
| 535 | |
| 536 | The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup(). |
| 537 | |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 538 | |
Hans Verkuil | c76cd63 | 2011-06-07 05:46:53 -0300 | [diff] [blame] | 539 | Handling autogain/gain-type Controls with Auto Clusters |
| 540 | ======================================================= |
| 541 | |
| 542 | A common type of control cluster is one that handles 'auto-foo/foo'-type |
| 543 | controls. Typical examples are autogain/gain, autoexposure/exposure, |
Hans Verkuil | 882a935 | 2011-08-26 08:35:59 -0300 | [diff] [blame] | 544 | autowhitebalance/red balance/blue balance. In all cases you have one control |
Hans Verkuil | c76cd63 | 2011-06-07 05:46:53 -0300 | [diff] [blame] | 545 | that determines whether another control is handled automatically by the hardware, |
| 546 | or whether it is under manual control from the user. |
| 547 | |
| 548 | If the cluster is in automatic mode, then the manual controls should be |
Hans Verkuil | 882a935 | 2011-08-26 08:35:59 -0300 | [diff] [blame] | 549 | marked inactive and volatile. When the volatile controls are read the |
| 550 | g_volatile_ctrl operation should return the value that the hardware's automatic |
| 551 | mode set up automatically. |
Hans Verkuil | c76cd63 | 2011-06-07 05:46:53 -0300 | [diff] [blame] | 552 | |
| 553 | If the cluster is put in manual mode, then the manual controls should become |
Hans Verkuil | 882a935 | 2011-08-26 08:35:59 -0300 | [diff] [blame] | 554 | active again and the volatile flag is cleared (so g_volatile_ctrl is no longer |
| 555 | called while in manual mode). In addition just before switching to manual mode |
| 556 | the current values as determined by the auto mode are copied as the new manual |
| 557 | values. |
Hans Verkuil | c76cd63 | 2011-06-07 05:46:53 -0300 | [diff] [blame] | 558 | |
| 559 | Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since |
| 560 | changing that control affects the control flags of the manual controls. |
| 561 | |
| 562 | In order to simplify this a special variation of v4l2_ctrl_cluster was |
| 563 | introduced: |
| 564 | |
| 565 | void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls, |
| 566 | u8 manual_val, bool set_volatile); |
| 567 | |
| 568 | The first two arguments are identical to v4l2_ctrl_cluster. The third argument |
| 569 | tells the framework which value switches the cluster into manual mode. The |
Hans Verkuil | 8836510 | 2011-08-26 07:35:14 -0300 | [diff] [blame] | 570 | last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls. |
Hans Verkuil | 882a935 | 2011-08-26 08:35:59 -0300 | [diff] [blame] | 571 | If it is false, then the manual controls are never volatile. You would typically |
| 572 | use that if the hardware does not give you the option to read back to values as |
| 573 | determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow |
| 574 | you to obtain the current gain value). |
Hans Verkuil | c76cd63 | 2011-06-07 05:46:53 -0300 | [diff] [blame] | 575 | |
| 576 | The first control of the cluster is assumed to be the 'auto' control. |
| 577 | |
| 578 | Using this function will ensure that you don't need to handle all the complex |
| 579 | flag and volatile handling. |
| 580 | |
| 581 | |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 582 | VIDIOC_LOG_STATUS Support |
| 583 | ========================= |
| 584 | |
| 585 | This ioctl allow you to dump the current status of a driver to the kernel log. |
| 586 | The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the |
| 587 | value of the controls owned by the given handler to the log. You can supply a |
| 588 | prefix as well. If the prefix didn't end with a space, then ': ' will be added |
| 589 | for you. |
| 590 | |
| 591 | |
| 592 | Different Handlers for Different Video Nodes |
| 593 | ============================================ |
| 594 | |
| 595 | Usually the V4L2 driver has just one control handler that is global for |
| 596 | all video nodes. But you can also specify different control handlers for |
| 597 | different video nodes. You can do that by manually setting the ctrl_handler |
| 598 | field of struct video_device. |
| 599 | |
| 600 | That is no problem if there are no subdevs involved but if there are, then |
| 601 | you need to block the automatic merging of subdev controls to the global |
| 602 | control handler. You do that by simply setting the ctrl_handler field in |
| 603 | struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer |
| 604 | merge subdev controls. |
| 605 | |
| 606 | After each subdev was added, you will then have to call v4l2_ctrl_add_handler |
| 607 | manually to add the subdev's control handler (sd->ctrl_handler) to the desired |
| 608 | control handler. This control handler may be specific to the video_device or |
| 609 | for a subset of video_device's. For example: the radio device nodes only have |
| 610 | audio controls, while the video and vbi device nodes share the same control |
| 611 | handler for the audio and video controls. |
| 612 | |
| 613 | If you want to have one handler (e.g. for a radio device node) have a subset |
| 614 | of another handler (e.g. for a video device node), then you should first add |
| 615 | the controls to the first handler, add the other controls to the second |
| 616 | handler and finally add the first handler to the second. For example: |
| 617 | |
| 618 | v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...); |
| 619 | v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); |
| 620 | v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...); |
| 621 | v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...); |
Hans Verkuil | 34a6b7d | 2012-09-14 07:15:03 -0300 | [diff] [blame] | 622 | v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler, NULL); |
| 623 | |
| 624 | The last argument to v4l2_ctrl_add_handler() is a filter function that allows |
| 625 | you to filter which controls will be added. Set it to NULL if you want to add |
| 626 | all controls. |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 627 | |
| 628 | Or you can add specific controls to a handler: |
| 629 | |
| 630 | volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...); |
| 631 | v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...); |
| 632 | v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...); |
| 633 | v4l2_ctrl_add_ctrl(&radio_ctrl_handler, volume); |
| 634 | |
| 635 | What you should not do is make two identical controls for two handlers. |
| 636 | For example: |
| 637 | |
| 638 | v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); |
| 639 | v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...); |
| 640 | |
| 641 | This would be bad since muting the radio would not change the video mute |
| 642 | control. The rule is to have one control for each hardware 'knob' that you |
| 643 | can twiddle. |
| 644 | |
| 645 | |
| 646 | Finding Controls |
| 647 | ================ |
| 648 | |
| 649 | Normally you have created the controls yourself and you can store the struct |
| 650 | v4l2_ctrl pointer into your own struct. |
| 651 | |
| 652 | But sometimes you need to find a control from another handler that you do |
| 653 | not own. For example, if you have to find a volume control from a subdev. |
| 654 | |
| 655 | You can do that by calling v4l2_ctrl_find: |
| 656 | |
| 657 | struct v4l2_ctrl *volume; |
| 658 | |
| 659 | volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME); |
| 660 | |
| 661 | Since v4l2_ctrl_find will lock the handler you have to be careful where you |
| 662 | use it. For example, this is not a good idea: |
| 663 | |
| 664 | struct v4l2_ctrl_handler ctrl_handler; |
| 665 | |
| 666 | v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...); |
| 667 | v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...); |
| 668 | |
| 669 | ...and in video_ops.s_ctrl: |
| 670 | |
| 671 | case V4L2_CID_BRIGHTNESS: |
| 672 | contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST); |
| 673 | ... |
| 674 | |
| 675 | When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so |
| 676 | attempting to find another control from the same handler will deadlock. |
| 677 | |
| 678 | It is recommended not to use this function from inside the control ops. |
| 679 | |
| 680 | |
| 681 | Inheriting Controls |
| 682 | =================== |
| 683 | |
| 684 | When one control handler is added to another using v4l2_ctrl_add_handler, then |
| 685 | by default all controls from one are merged to the other. But a subdev might |
| 686 | have low-level controls that make sense for some advanced embedded system, but |
| 687 | not when it is used in consumer-level hardware. In that case you want to keep |
| 688 | those low-level controls local to the subdev. You can do this by simply |
| 689 | setting the 'is_private' flag of the control to 1: |
| 690 | |
| 691 | static const struct v4l2_ctrl_config ctrl_private = { |
| 692 | .ops = &ctrl_custom_ops, |
| 693 | .id = V4L2_CID_..., |
| 694 | .name = "Some Private Control", |
| 695 | .type = V4L2_CTRL_TYPE_INTEGER, |
| 696 | .max = 15, |
| 697 | .step = 1, |
| 698 | .is_private = 1, |
| 699 | }; |
| 700 | |
| 701 | ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL); |
| 702 | |
| 703 | These controls will now be skipped when v4l2_ctrl_add_handler is called. |
| 704 | |
| 705 | |
| 706 | V4L2_CTRL_TYPE_CTRL_CLASS Controls |
| 707 | ================================== |
| 708 | |
| 709 | Controls of this type can be used by GUIs to get the name of the control class. |
| 710 | A fully featured GUI can make a dialog with multiple tabs with each tab |
| 711 | containing the controls belonging to a particular control class. The name of |
| 712 | each tab can be found by querying a special control with ID <control class | 1>. |
| 713 | |
| 714 | Drivers do not have to care about this. The framework will automatically add |
| 715 | a control of this type whenever the first control belonging to a new control |
| 716 | class is added. |
| 717 | |
| 718 | |
Hans Verkuil | 8ac7a94 | 2012-09-07 04:46:39 -0300 | [diff] [blame] | 719 | Adding Notify Callbacks |
| 720 | ======================= |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 721 | |
Hans Verkuil | 8ac7a94 | 2012-09-07 04:46:39 -0300 | [diff] [blame] | 722 | Sometimes the platform or bridge driver needs to be notified when a control |
| 723 | from a sub-device driver changes. You can set a notify callback by calling |
| 724 | this function: |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 725 | |
Hans Verkuil | 8ac7a94 | 2012-09-07 04:46:39 -0300 | [diff] [blame] | 726 | void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, |
| 727 | void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv); |
Hans Verkuil | a42b57f | 2010-08-01 14:35:53 -0300 | [diff] [blame] | 728 | |
Hans Verkuil | 8ac7a94 | 2012-09-07 04:46:39 -0300 | [diff] [blame] | 729 | Whenever the give control changes value the notify callback will be called |
| 730 | with a pointer to the control and the priv pointer that was passed with |
| 731 | v4l2_ctrl_notify. Note that the control's handler lock is held when the |
| 732 | notify function is called. |
| 733 | |
| 734 | There can be only one notify function per control handler. Any attempt |
| 735 | to set another notify function will cause a WARN_ON. |