aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/video4linux
diff options
context:
space:
mode:
authorHans Verkuil <hverkuil@xs4all.nl>2010-08-01 13:35:53 -0400
committerMauro Carvalho Chehab <mchehab@redhat.com>2010-08-08 22:43:04 -0400
commita42b57f5aacf2b43f3e7931e8b9c609051839aa8 (patch)
tree2e128ba1699c83d129db620f96d5f41ed996cb0c /Documentation/video4linux
parent6dd5aff3cab284556952d96f1112b17299e126d8 (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')
-rw-r--r--Documentation/video4linux/v4l2-controls.txt648
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 @@
1Introduction
2============
3
4The V4L2 control API seems simple enough, but quickly becomes very hard to
5implement correctly in drivers. But much of the code needed to handle controls
6is actually not driver specific and can be moved to the V4L core framework.
7
8After all, the only part that a driver developer is interested in is:
9
101) How do I add a control?
112) How do I set the control's value? (i.e. s_ctrl)
12
13And occasionally:
14
153) How do I get the control's value? (i.e. g_volatile_ctrl)
164) How do I validate the user's proposed control value? (i.e. try_ctrl)
17
18All the rest is something that can be done centrally.
19
20The control framework was created in order to implement all the rules of the
21V4L2 specification with respect to controls in a central place. And to make
22life as easy as possible for the driver developer.
23
24Note that the control framework relies on the presence of a struct v4l2_device
25for V4L2 drivers and struct v4l2_subdev for sub-device drivers.
26
27
28Objects in the framework
29========================
30
31There are two main objects:
32
33The v4l2_ctrl object describes the control properties and keeps track of the
34control's value (both the current value and the proposed new value).
35
36v4l2_ctrl_handler is the object that keeps track of controls. It maintains a
37list of v4l2_ctrl objects that it owns and another list of references to
38controls, possibly to controls owned by other handlers.
39
40
41Basic usage for V4L2 and sub-device drivers
42===========================================
43
441) Prepare the driver:
45
461.1) Add the handler to your driver's top-level struct:
47
48 struct foo_dev {
49 ...
50 struct v4l2_ctrl_handler ctrl_handler;
51 ...
52 };
53
54 struct foo_dev *foo;
55
561.2) Initialize the handler:
57
58 v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
59
60 The second argument is a hint telling the function how many controls this
61 handler is expected to handle. It will allocate a hashtable based on this
62 information. It is a hint only.
63
641.3) Hook the control handler into the driver:
65
661.3.1) For V4L2 drivers do this:
67
68 struct foo_dev {
69 ...
70 struct v4l2_device v4l2_dev;
71 ...
72 struct v4l2_ctrl_handler ctrl_handler;
73 ...
74 };
75
76 foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;
77
78 Where foo->v4l2_dev is of type struct v4l2_device.
79
80 Finally, remove all control functions from your v4l2_ioctl_ops:
81 vidioc_queryctrl, vidioc_querymenu, vidioc_g_ctrl, vidioc_s_ctrl,
82 vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls.
83 Those are now no longer needed.
84
851.3.2) For sub-device drivers do this:
86
87 struct foo_dev {
88 ...
89 struct v4l2_subdev sd;
90 ...
91 struct v4l2_ctrl_handler ctrl_handler;
92 ...
93 };
94
95 foo->sd.ctrl_handler = &foo->ctrl_handler;
96
97 Where foo->sd is of type struct v4l2_subdev.
98
99 And set all core control ops in your struct v4l2_subdev_core_ops to these
100 helpers:
101
102 .queryctrl = v4l2_subdev_queryctrl,
103 .querymenu = v4l2_subdev_querymenu,
104 .g_ctrl = v4l2_subdev_g_ctrl,
105 .s_ctrl = v4l2_subdev_s_ctrl,
106 .g_ext_ctrls = v4l2_subdev_g_ext_ctrls,
107 .try_ext_ctrls = v4l2_subdev_try_ext_ctrls,
108 .s_ext_ctrls = v4l2_subdev_s_ext_ctrls,
109
110 Note: this is a temporary solution only. Once all V4L2 drivers that depend
111 on subdev drivers are converted to the control framework these helpers will
112 no longer be needed.
113
1141.4) Clean up the handler at the end:
115
116 v4l2_ctrl_handler_free(&foo->ctrl_handler);
117
118
1192) Add controls:
120
121You add non-menu controls by calling v4l2_ctrl_new_std:
122
123 struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
124 const struct v4l2_ctrl_ops *ops,
125 u32 id, s32 min, s32 max, u32 step, s32 def);
126
127Menu controls are added by calling v4l2_ctrl_new_std_menu:
128
129 struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
130 const struct v4l2_ctrl_ops *ops,
131 u32 id, s32 max, s32 skip_mask, s32 def);
132
133These 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
152The v4l2_ctrl_new_std function returns the v4l2_ctrl pointer to the new
153control, but if you do not need to access the pointer outside the control ops,
154then there is no need to store it.
155
156The v4l2_ctrl_new_std function will fill in most fields based on the control
157ID except for the min, max, step and default values. These are passed in the
158last four arguments. These values are driver specific while control attributes
159like type, name, flags are all global. The control's current value will be set
160to the default value.
161
162The v4l2_ctrl_new_std_menu function is very similar but it is used for menu
163controls. There is no min argument since that is always 0 for menu controls,
164and instead of a step there is a skip_mask argument: if bit X is 1, then menu
165item X is skipped.
166
167Note that if something fails, the function will return NULL or an error and
168set ctrl_handler->error to the error code. If ctrl_handler->error was already
169set, then it will just return and do nothing. This is also true for
170v4l2_ctrl_handler_init if it cannot allocate the internal data structure.
171
172This makes it easy to init the handler and just add all controls and only check
173the error code at the end. Saves a lot of repetitive error checking.
174
175It is recommended to add controls in ascending control ID order: it will be
176a bit faster that way.
177
1783) Optionally force initial control setup:
179
180 v4l2_ctrl_handler_setup(&foo->ctrl_handler);
181
182This will call s_ctrl for all controls unconditionally. Effectively this
183initializes the hardware to the default control values. It is recommended
184that you do this as this ensures that both the internal data structures and
185the hardware are in sync.
186
1874) 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
193Usually 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
210The control ops are called with the v4l2_ctrl pointer as argument.
211The new control value has already been validated, so all you need to do is
212to actually update the hardware registers.
213
214You're done! And this is sufficient for most of the drivers we have. No need
215to do any validation of control values, or implement QUERYCTRL/QUERYMENU. And
216G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported.
217
218
219==============================================================================
220
221The remainder of this document deals with more advanced topics and scenarios.
222In practice the basic usage as described above is sufficient for most drivers.
223
224===============================================================================
225
226
227Inheriting Controls
228===================
229
230When a sub-device is registered with a V4L2 driver by calling
231v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev
232and v4l2_device are set, then the controls of the subdev will become
233automatically available in the V4L2 driver as well. If the subdev driver
234contains controls that already exist in the V4L2 driver, then those will be
235skipped (so a V4L2 driver can always override a subdev control).
236
237What happens here is that v4l2_device_register_subdev() calls
238v4l2_ctrl_add_handler() adding the controls of the subdev to the controls
239of v4l2_device.
240
241
242Accessing Control Values
243========================
244
245The 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
261Within the control ops you can freely use these. The val and val64 speak for
262themselves. The string pointers point to character buffers of length
263ctrl->maximum + 1, and are always 0-terminated.
264
265In most cases 'cur' contains the current cached control value. When you create
266a new control this value is made identical to the default value. After calling
267v4l2_ctrl_handler_setup() this value is passed to the hardware. It is generally
268a good idea to call this function.
269
270Whenever a new value is set that new value is automatically cached. This means
271that most drivers do not need to implement the g_volatile_ctrl() op. The
272exception is for controls that return a volatile register such as a signal
273strength read-out that changes continuously. In that case you will need to
274implement 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
285The 'new value' union is not used in g_volatile_ctrl. In general controls
286that need to implement g_volatile_ctrl are read-only controls.
287
288To 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
294For try/s_ctrl the new values (i.e. as passed by the user) are filled in and
295you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union
296contains the current value, which you can use (but not change!) as well.
297
298If s_ctrl returns 0 (OK), then the control framework will copy the new final
299values to the 'cur' union.
300
301While in g_volatile/s/try_ctrl you can access the value of all controls owned
302by the same handler since the handler's lock is held. If you need to access
303the value of controls owned by other handlers, then you have to be very careful
304not to introduce deadlocks.
305
306Outside of the control ops you have to go through to helper functions to get
307or 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
312These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls
313do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that
314will result in a deadlock since these helpers lock the handler as well.
315
316You 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
324Menu Controls
325=============
326
327The v4l2_ctrl struct contains this union:
328
329 union {
330 u32 step;
331 u32 menu_skip_mask;
332 };
333
334For menu controls menu_skip_mask is used. What it does is that it allows you
335to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU
336implementation where you can return -EINVAL if a certain menu item is not
337present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for
338menu controls.
339
340A good example is the MPEG Audio Layer II Bitrate menu control where the
341menu is a list of standardized possible bitrates. But in practice hardware
342implementations will only support a subset of those. By setting the skip
343mask you can tell the framework which menu items should be skipped. Setting
344it to 0 means that all menu items are supported.
345
346You set this mask either through the v4l2_ctrl_config struct for a custom
347control, or by calling v4l2_ctrl_new_std_menu().
348
349
350Custom Controls
351===============
352
353Driver 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
367The last argument is the priv pointer which can be set to driver-specific
368private data.
369
370The v4l2_ctrl_config struct also has fields to set the is_private and is_volatile
371flags.
372
373If the name field is not set, then the framework will assume this is a standard
374control and will fill in the name, type and flags fields accordingly.
375
376
377Active and Grabbed Controls
378===========================
379
380If you get more complex relationships between controls, then you may have to
381activate and deactivate controls. For example, if the Chroma AGC control is
382on, then the Chroma Gain control is inactive. That is, you may set it, but
383the value will not be used by the hardware as long as the automatic gain
384control is on. Typically user interfaces can disable such input fields.
385
386You can set the 'active' status using v4l2_ctrl_activate(). By default all
387controls are active. Note that the framework does not check for this flag.
388It is meant purely for GUIs. The function is typically called from within
389s_ctrl.
390
391The other flag is the 'grabbed' flag. A grabbed control means that you cannot
392change it because it is in use by some resource. Typical examples are MPEG
393bitrate controls that cannot be changed while capturing is in progress.
394
395If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework
396will return -EBUSY if an attempt is made to set this control. The
397v4l2_ctrl_grab() function is typically called from the driver when it
398starts or stops streaming.
399
400
401Control Clusters
402================
403
404By default all controls are independent from the others. But in more
405complex scenarios you can get dependencies from one control to another.
406In 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
422From now on whenever one or more of the controls belonging to the same
423cluster is set (or 'gotten', or 'tried'), only the control ops of the first
424control ('volume' in this example) is called. You effectively create a new
425composite control. Similar to how a 'struct' works in C.
426
427So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set
428all 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
448In 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
453Note that controls in a cluster may be NULL. For example, if for some
454reason mute was never added (because the hardware doesn't support that
455particular feature), then mute will be NULL. So in that case we have a
456cluster of 2 controls, of which only 1 is actually instantiated. The
457only restriction is that the first control of the cluster must always be
458present, since that is the 'master' control of the cluster. The master
459control is the one that identifies the cluster and that provides the
460pointer to the v4l2_ctrl_ops struct that is used for that cluster.
461
462Obviously, all controls in the cluster array must be initialized to either
463a valid control or to NULL.
464
465
466VIDIOC_LOG_STATUS Support
467=========================
468
469This ioctl allow you to dump the current status of a driver to the kernel log.
470The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the
471value of the controls owned by the given handler to the log. You can supply a
472prefix as well. If the prefix didn't end with a space, then ': ' will be added
473for you.
474
475
476Different Handlers for Different Video Nodes
477============================================
478
479Usually the V4L2 driver has just one control handler that is global for
480all video nodes. But you can also specify different control handlers for
481different video nodes. You can do that by manually setting the ctrl_handler
482field of struct video_device.
483
484That is no problem if there are no subdevs involved but if there are, then
485you need to block the automatic merging of subdev controls to the global
486control handler. You do that by simply setting the ctrl_handler field in
487struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer
488merge subdev controls.
489
490After each subdev was added, you will then have to call v4l2_ctrl_add_handler
491manually to add the subdev's control handler (sd->ctrl_handler) to the desired
492control handler. This control handler may be specific to the video_device or
493for a subset of video_device's. For example: the radio device nodes only have
494audio controls, while the video and vbi device nodes share the same control
495handler for the audio and video controls.
496
497If you want to have one handler (e.g. for a radio device node) have a subset
498of another handler (e.g. for a video device node), then you should first add
499the controls to the first handler, add the other controls to the second
500handler 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
508Or 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
515What you should not do is make two identical controls for two handlers.
516For 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
521This would be bad since muting the radio would not change the video mute
522control. The rule is to have one control for each hardware 'knob' that you
523can twiddle.
524
525
526Finding Controls
527================
528
529Normally you have created the controls yourself and you can store the struct
530v4l2_ctrl pointer into your own struct.
531
532But sometimes you need to find a control from another handler that you do
533not own. For example, if you have to find a volume control from a subdev.
534
535You 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
541Since v4l2_ctrl_find will lock the handler you have to be careful where you
542use 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
555When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so
556attempting to find another control from the same handler will deadlock.
557
558It is recommended not to use this function from inside the control ops.
559
560
561Inheriting Controls
562===================
563
564When one control handler is added to another using v4l2_ctrl_add_handler, then
565by default all controls from one are merged to the other. But a subdev might
566have low-level controls that make sense for some advanced embedded system, but
567not when it is used in consumer-level hardware. In that case you want to keep
568those low-level controls local to the subdev. You can do this by simply
569setting 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
583These controls will now be skipped when v4l2_ctrl_add_handler is called.
584
585
586V4L2_CTRL_TYPE_CTRL_CLASS Controls
587==================================
588
589Controls of this type can be used by GUIs to get the name of the control class.
590A fully featured GUI can make a dialog with multiple tabs with each tab
591containing the controls belonging to a particular control class. The name of
592each tab can be found by querying a special control with ID <control class | 1>.
593
594Drivers do not have to care about this. The framework will automatically add
595a control of this type whenever the first control belonging to a new control
596class is added.
597
598
599Differences from the Spec
600=========================
601
602There are a few places where the framework acts slightly differently from the
603V4L2 Specification. Those differences are described in this section. We will
604have to see whether we need to adjust the spec or not.
605
6061) It is no longer required to have all controls contained in a
607v4l2_ext_control array be from the same control class. The framework will be
608able to handle any type of control in the array. You need to set ctrl_class
609to 0 in order to enable this. If ctrl_class is non-zero, then it will still
610check that all controls belong to that control class.
611
612If you set ctrl_class to 0 and count to 0, then it will only return an error
613if there are no controls at all.
614
6152) Clarified the way error_idx works. For get and set it will be equal to
616count if nothing was done yet. If it is less than count then only the controls
617up to error_idx-1 were successfully applied.
618
6193) When attempting to read a button control the framework will return -EACCES
620instead of -EINVAL as stated in the spec. It seems to make more sense since
621button controls are write-only controls.
622
6234) Attempting to write to a read-only control will return -EACCES instead of
624-EINVAL as the spec says.
625
6265) The spec does not mention what should happen when you try to set/get a
627control class controls. ivtv currently returns -EINVAL (indicating that the
628control ID does not exist) while the framework will return -EACCES, which
629makes more sense.
630
631
632Proposals for Extensions
633========================
634
635Some ideas for future extensions to the spec:
636
6371) Add a V4L2_CTRL_FLAG_HEX to have values shown as hexadecimal instead of
638decimal. Useful for e.g. video_mute_yuv.
639
6402) It is possible to mark in the controls array which controls have been
641successfully written and which failed by for example adding a bit to the
642control ID. Not sure if it is worth the effort, though.
643
6443) Trying to set volatile inactive controls should result in -EACCESS.
645
6464) Add a new flag to mark volatile controls. Any application that wants
647to store the state of the controls can then skip volatile inactive controls.
648Currently it is not possible to detect such controls.