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