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