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