Merge tag 'for-linus-4.14b-rc2-tag' of git://git.kernel.org/pub/scm/linux/kernel...
[platform/kernel/linux-rpi.git] / include / media / v4l2-ctrls.h
1 /*
2  *  V4L2 controls support header.
3  *
4  *  Copyright (C) 2010  Hans Verkuil <hverkuil@xs4all.nl>
5  *
6  *  This program is free software; you can redistribute it and/or modify
7  *  it under the terms of the GNU General Public License as published by
8  *  the Free Software Foundation; either version 2 of the License, or
9  *  (at your option) any later version.
10  *
11  *  This program is distributed in the hope that it will be useful,
12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  *  GNU General Public License for more details.
15  */
16
17 #ifndef _V4L2_CTRLS_H
18 #define _V4L2_CTRLS_H
19
20 #include <linux/list.h>
21 #include <linux/mutex.h>
22 #include <linux/videodev2.h>
23
24 /* forward references */
25 struct file;
26 struct v4l2_ctrl_handler;
27 struct v4l2_ctrl_helper;
28 struct v4l2_ctrl;
29 struct video_device;
30 struct v4l2_subdev;
31 struct v4l2_subscribed_event;
32 struct v4l2_fh;
33 struct poll_table_struct;
34
35 /**
36  * union v4l2_ctrl_ptr - A pointer to a control value.
37  * @p_s32:      Pointer to a 32-bit signed value.
38  * @p_s64:      Pointer to a 64-bit signed value.
39  * @p_u8:       Pointer to a 8-bit unsigned value.
40  * @p_u16:      Pointer to a 16-bit unsigned value.
41  * @p_u32:      Pointer to a 32-bit unsigned value.
42  * @p_char:     Pointer to a string.
43  * @p:          Pointer to a compound value.
44  */
45 union v4l2_ctrl_ptr {
46         s32 *p_s32;
47         s64 *p_s64;
48         u8 *p_u8;
49         u16 *p_u16;
50         u32 *p_u32;
51         char *p_char;
52         void *p;
53 };
54
55 /**
56  * struct v4l2_ctrl_ops - The control operations that the driver has to provide.
57  *
58  * @g_volatile_ctrl: Get a new value for this control. Generally only relevant
59  *              for volatile (and usually read-only) controls such as a control
60  *              that returns the current signal strength which changes
61  *              continuously.
62  *              If not set, then the currently cached value will be returned.
63  * @try_ctrl:   Test whether the control's value is valid. Only relevant when
64  *              the usual min/max/step checks are not sufficient.
65  * @s_ctrl:     Actually set the new control value. s_ctrl is compulsory. The
66  *              ctrl->handler->lock is held when these ops are called, so no
67  *              one else can access controls owned by that handler.
68  */
69 struct v4l2_ctrl_ops {
70         int (*g_volatile_ctrl)(struct v4l2_ctrl *ctrl);
71         int (*try_ctrl)(struct v4l2_ctrl *ctrl);
72         int (*s_ctrl)(struct v4l2_ctrl *ctrl);
73 };
74
75 /**
76  * struct v4l2_ctrl_type_ops - The control type operations that the driver
77  *                             has to provide.
78  *
79  * @equal: return true if both values are equal.
80  * @init: initialize the value.
81  * @log: log the value.
82  * @validate: validate the value. Return 0 on success and a negative value
83  *      otherwise.
84  */
85 struct v4l2_ctrl_type_ops {
86         bool (*equal)(const struct v4l2_ctrl *ctrl, u32 idx,
87                       union v4l2_ctrl_ptr ptr1,
88                       union v4l2_ctrl_ptr ptr2);
89         void (*init)(const struct v4l2_ctrl *ctrl, u32 idx,
90                      union v4l2_ctrl_ptr ptr);
91         void (*log)(const struct v4l2_ctrl *ctrl);
92         int (*validate)(const struct v4l2_ctrl *ctrl, u32 idx,
93                         union v4l2_ctrl_ptr ptr);
94 };
95
96 /**
97  * typedef v4l2_ctrl_notify_fnc - typedef for a notify argument with a function
98  *      that should be called when a control value has changed.
99  *
100  * @ctrl: pointer to struct &v4l2_ctrl
101  * @priv: control private data
102  *
103  * This typedef definition is used as an argument to v4l2_ctrl_notify()
104  * and as an argument at struct &v4l2_ctrl_handler.
105  */
106 typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
107
108 /**
109  * struct v4l2_ctrl - The control structure.
110  *
111  * @node:       The list node.
112  * @ev_subs:    The list of control event subscriptions.
113  * @handler:    The handler that owns the control.
114  * @cluster:    Point to start of cluster array.
115  * @ncontrols:  Number of controls in cluster array.
116  * @done:       Internal flag: set for each processed control.
117  * @is_new:     Set when the user specified a new value for this control. It
118  *              is also set when called from v4l2_ctrl_handler_setup(). Drivers
119  *              should never set this flag.
120  * @has_changed: Set when the current value differs from the new value. Drivers
121  *              should never use this flag.
122  * @is_private: If set, then this control is private to its handler and it
123  *              will not be added to any other handlers. Drivers can set
124  *              this flag.
125  * @is_auto:   If set, then this control selects whether the other cluster
126  *              members are in 'automatic' mode or 'manual' mode. This is
127  *              used for autogain/gain type clusters. Drivers should never
128  *              set this flag directly.
129  * @is_int:    If set, then this control has a simple integer value (i.e. it
130  *              uses ctrl->val).
131  * @is_string: If set, then this control has type %V4L2_CTRL_TYPE_STRING.
132  * @is_ptr:     If set, then this control is an array and/or has type >=
133  *              %V4L2_CTRL_COMPOUND_TYPES
134  *              and/or has type %V4L2_CTRL_TYPE_STRING. In other words, &struct
135  *              v4l2_ext_control uses field p to point to the data.
136  * @is_array: If set, then this control contains an N-dimensional array.
137  * @has_volatiles: If set, then one or more members of the cluster are volatile.
138  *              Drivers should never touch this flag.
139  * @call_notify: If set, then call the handler's notify function whenever the
140  *              control's value changes.
141  * @manual_mode_value: If the is_auto flag is set, then this is the value
142  *              of the auto control that determines if that control is in
143  *              manual mode. So if the value of the auto control equals this
144  *              value, then the whole cluster is in manual mode. Drivers should
145  *              never set this flag directly.
146  * @ops:        The control ops.
147  * @type_ops:   The control type ops.
148  * @id: The control ID.
149  * @name:       The control name.
150  * @type:       The control type.
151  * @minimum:    The control's minimum value.
152  * @maximum:    The control's maximum value.
153  * @default_value: The control's default value.
154  * @step:       The control's step value for non-menu controls.
155  * @elems:      The number of elements in the N-dimensional array.
156  * @elem_size:  The size in bytes of the control.
157  * @dims:       The size of each dimension.
158  * @nr_of_dims:The number of dimensions in @dims.
159  * @menu_skip_mask: The control's skip mask for menu controls. This makes it
160  *              easy to skip menu items that are not valid. If bit X is set,
161  *              then menu item X is skipped. Of course, this only works for
162  *              menus with <= 32 menu items. There are no menus that come
163  *              close to that number, so this is OK. Should we ever need more,
164  *              then this will have to be extended to a u64 or a bit array.
165  * @qmenu:      A const char * array for all menu items. Array entries that are
166  *              empty strings ("") correspond to non-existing menu items (this
167  *              is in addition to the menu_skip_mask above). The last entry
168  *              must be NULL.
169  * @flags:      The control's flags.
170  * @cur:        The control's current value.
171  * @val:        The control's new s32 value.
172  * @priv:       The control's private pointer. For use by the driver. It is
173  *              untouched by the control framework. Note that this pointer is
174  *              not freed when the control is deleted. Should this be needed
175  *              then a new internal bitfield can be added to tell the framework
176  *              to free this pointer.
177  * @p_cur:      The control's current value represented via a union with
178  *              provides a standard way of accessing control types
179  *              through a pointer.
180  * @p_new:      The control's new value represented via a union with provides
181  *              a standard way of accessing control types
182  *              through a pointer.
183  */
184 struct v4l2_ctrl {
185         /* Administrative fields */
186         struct list_head node;
187         struct list_head ev_subs;
188         struct v4l2_ctrl_handler *handler;
189         struct v4l2_ctrl **cluster;
190         unsigned int ncontrols;
191
192         unsigned int done:1;
193
194         unsigned int is_new:1;
195         unsigned int has_changed:1;
196         unsigned int is_private:1;
197         unsigned int is_auto:1;
198         unsigned int is_int:1;
199         unsigned int is_string:1;
200         unsigned int is_ptr:1;
201         unsigned int is_array:1;
202         unsigned int has_volatiles:1;
203         unsigned int call_notify:1;
204         unsigned int manual_mode_value:8;
205
206         const struct v4l2_ctrl_ops *ops;
207         const struct v4l2_ctrl_type_ops *type_ops;
208         u32 id;
209         const char *name;
210         enum v4l2_ctrl_type type;
211         s64 minimum, maximum, default_value;
212         u32 elems;
213         u32 elem_size;
214         u32 dims[V4L2_CTRL_MAX_DIMS];
215         u32 nr_of_dims;
216         union {
217                 u64 step;
218                 u64 menu_skip_mask;
219         };
220         union {
221                 const char * const *qmenu;
222                 const s64 *qmenu_int;
223         };
224         unsigned long flags;
225         void *priv;
226         s32 val;
227         struct {
228                 s32 val;
229         } cur;
230
231         union v4l2_ctrl_ptr p_new;
232         union v4l2_ctrl_ptr p_cur;
233 };
234
235 /**
236  * struct v4l2_ctrl_ref - The control reference.
237  *
238  * @node:       List node for the sorted list.
239  * @next:       Single-link list node for the hash.
240  * @ctrl:       The actual control information.
241  * @helper:     Pointer to helper struct. Used internally in
242  *              ``prepare_ext_ctrls`` function at ``v4l2-ctrl.c``.
243  *
244  * Each control handler has a list of these refs. The list_head is used to
245  * keep a sorted-by-control-ID list of all controls, while the next pointer
246  * is used to link the control in the hash's bucket.
247  */
248 struct v4l2_ctrl_ref {
249         struct list_head node;
250         struct v4l2_ctrl_ref *next;
251         struct v4l2_ctrl *ctrl;
252         struct v4l2_ctrl_helper *helper;
253 };
254
255 /**
256  * struct v4l2_ctrl_handler - The control handler keeps track of all the
257  *      controls: both the controls owned by the handler and those inherited
258  *      from other handlers.
259  *
260  * @_lock:      Default for "lock".
261  * @lock:       Lock to control access to this handler and its controls.
262  *              May be replaced by the user right after init.
263  * @ctrls:      The list of controls owned by this handler.
264  * @ctrl_refs:  The list of control references.
265  * @cached:     The last found control reference. It is common that the same
266  *              control is needed multiple times, so this is a simple
267  *              optimization.
268  * @buckets:    Buckets for the hashing. Allows for quick control lookup.
269  * @notify:     A notify callback that is called whenever the control changes
270  *              value.
271  *              Note that the handler's lock is held when the notify function
272  *              is called!
273  * @notify_priv: Passed as argument to the v4l2_ctrl notify callback.
274  * @nr_of_buckets: Total number of buckets in the array.
275  * @error:      The error code of the first failed control addition.
276  */
277 struct v4l2_ctrl_handler {
278         struct mutex _lock;
279         struct mutex *lock;
280         struct list_head ctrls;
281         struct list_head ctrl_refs;
282         struct v4l2_ctrl_ref *cached;
283         struct v4l2_ctrl_ref **buckets;
284         v4l2_ctrl_notify_fnc notify;
285         void *notify_priv;
286         u16 nr_of_buckets;
287         int error;
288 };
289
290 /**
291  * struct v4l2_ctrl_config - Control configuration structure.
292  *
293  * @ops:        The control ops.
294  * @type_ops:   The control type ops. Only needed for compound controls.
295  * @id: The control ID.
296  * @name:       The control name.
297  * @type:       The control type.
298  * @min:        The control's minimum value.
299  * @max:        The control's maximum value.
300  * @step:       The control's step value for non-menu controls.
301  * @def:        The control's default value.
302  * @dims:       The size of each dimension.
303  * @elem_size:  The size in bytes of the control.
304  * @flags:      The control's flags.
305  * @menu_skip_mask: The control's skip mask for menu controls. This makes it
306  *              easy to skip menu items that are not valid. If bit X is set,
307  *              then menu item X is skipped. Of course, this only works for
308  *              menus with <= 64 menu items. There are no menus that come
309  *              close to that number, so this is OK. Should we ever need more,
310  *              then this will have to be extended to a bit array.
311  * @qmenu:      A const char * array for all menu items. Array entries that are
312  *              empty strings ("") correspond to non-existing menu items (this
313  *              is in addition to the menu_skip_mask above). The last entry
314  *              must be NULL.
315  * @qmenu_int:  A const s64 integer array for all menu items of the type
316  *              V4L2_CTRL_TYPE_INTEGER_MENU.
317  * @is_private: If set, then this control is private to its handler and it
318  *              will not be added to any other handlers.
319  */
320 struct v4l2_ctrl_config {
321         const struct v4l2_ctrl_ops *ops;
322         const struct v4l2_ctrl_type_ops *type_ops;
323         u32 id;
324         const char *name;
325         enum v4l2_ctrl_type type;
326         s64 min;
327         s64 max;
328         u64 step;
329         s64 def;
330         u32 dims[V4L2_CTRL_MAX_DIMS];
331         u32 elem_size;
332         u32 flags;
333         u64 menu_skip_mask;
334         const char * const *qmenu;
335         const s64 *qmenu_int;
336         unsigned int is_private:1;
337 };
338
339 /**
340  * v4l2_ctrl_fill - Fill in the control fields based on the control ID.
341  *
342  * @id: ID of the control
343  * @name: pointer to be filled with a string with the name of the control
344  * @type: pointer for storing the type of the control
345  * @min: pointer for storing the minimum value for the control
346  * @max: pointer for storing the maximum value for the control
347  * @step: pointer for storing the control step
348  * @def: pointer for storing the default value for the control
349  * @flags: pointer for storing the flags to be used on the control
350  *
351  * This works for all standard V4L2 controls.
352  * For non-standard controls it will only fill in the given arguments
353  * and @name content will be set to %NULL.
354  *
355  * This function will overwrite the contents of @name, @type and @flags.
356  * The contents of @min, @max, @step and @def may be modified depending on
357  * the type.
358  *
359  * .. note::
360  *
361  *    Do not use in drivers! It is used internally for backwards compatibility
362  *    control handling only. Once all drivers are converted to use the new
363  *    control framework this function will no longer be exported.
364  */
365 void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
366                     s64 *min, s64 *max, u64 *step, s64 *def, u32 *flags);
367
368
369 /**
370  * v4l2_ctrl_handler_init_class() - Initialize the control handler.
371  * @hdl:        The control handler.
372  * @nr_of_controls_hint: A hint of how many controls this handler is
373  *              expected to refer to. This is the total number, so including
374  *              any inherited controls. It doesn't have to be precise, but if
375  *              it is way off, then you either waste memory (too many buckets
376  *              are allocated) or the control lookup becomes slower (not enough
377  *              buckets are allocated, so there are more slow list lookups).
378  *              It will always work, though.
379  * @key:        Used by the lock validator if CONFIG_LOCKDEP is set.
380  * @name:       Used by the lock validator if CONFIG_LOCKDEP is set.
381  *
382  * .. attention::
383  *
384  *    Never use this call directly, always use the v4l2_ctrl_handler_init()
385  *    macro that hides the @key and @name arguments.
386  *
387  * Return: returns an error if the buckets could not be allocated. This
388  * error will also be stored in @hdl->error.
389  */
390 int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
391                                  unsigned int nr_of_controls_hint,
392                                  struct lock_class_key *key, const char *name);
393
394 #ifdef CONFIG_LOCKDEP
395
396 /**
397  * v4l2_ctrl_handler_init - helper function to create a static struct
398  *       &lock_class_key and calls v4l2_ctrl_handler_init_class()
399  *
400  * @hdl:        The control handler.
401  * @nr_of_controls_hint: A hint of how many controls this handler is
402  *              expected to refer to. This is the total number, so including
403  *              any inherited controls. It doesn't have to be precise, but if
404  *              it is way off, then you either waste memory (too many buckets
405  *              are allocated) or the control lookup becomes slower (not enough
406  *              buckets are allocated, so there are more slow list lookups).
407  *              It will always work, though.
408  *
409  * This helper function creates a static struct &lock_class_key and
410  * calls v4l2_ctrl_handler_init_class(), providing a proper name for the lock
411  * validador.
412  *
413  * Use this helper function to initialize a control handler.
414  */
415 #define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint)                \
416 (                                                                       \
417         ({                                                              \
418                 static struct lock_class_key _key;                      \
419                 v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint,  \
420                                         &_key,                          \
421                                         KBUILD_BASENAME ":"             \
422                                         __stringify(__LINE__) ":"       \
423                                         "(" #hdl ")->_lock");           \
424         })                                                              \
425 )
426 #else
427 #define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint)                \
428         v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint, NULL, NULL)
429 #endif
430
431 /**
432  * v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
433  * the control list.
434  * @hdl:        The control handler.
435  *
436  * Does nothing if @hdl == NULL.
437  */
438 void v4l2_ctrl_handler_free(struct v4l2_ctrl_handler *hdl);
439
440 /**
441  * v4l2_ctrl_lock() - Helper function to lock the handler
442  * associated with the control.
443  * @ctrl:       The control to lock.
444  */
445 static inline void v4l2_ctrl_lock(struct v4l2_ctrl *ctrl)
446 {
447         mutex_lock(ctrl->handler->lock);
448 }
449
450 /**
451  * v4l2_ctrl_unlock() - Helper function to unlock the handler
452  * associated with the control.
453  * @ctrl:       The control to unlock.
454  */
455 static inline void v4l2_ctrl_unlock(struct v4l2_ctrl *ctrl)
456 {
457         mutex_unlock(ctrl->handler->lock);
458 }
459
460 /**
461  * __v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
462  * to the handler to initialize the hardware to the current control values. The
463  * caller is responsible for acquiring the control handler mutex on behalf of
464  * __v4l2_ctrl_handler_setup().
465  * @hdl:        The control handler.
466  *
467  * Button controls will be skipped, as are read-only controls.
468  *
469  * If @hdl == NULL, then this just returns 0.
470  */
471 int __v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
472
473 /**
474  * v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
475  * to the handler to initialize the hardware to the current control values.
476  * @hdl:        The control handler.
477  *
478  * Button controls will be skipped, as are read-only controls.
479  *
480  * If @hdl == NULL, then this just returns 0.
481  */
482 int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
483
484 /**
485  * v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
486  * @hdl:        The control handler.
487  * @prefix:     The prefix to use when logging the control values. If the
488  *              prefix does not end with a space, then ": " will be added
489  *              after the prefix. If @prefix == NULL, then no prefix will be
490  *              used.
491  *
492  * For use with VIDIOC_LOG_STATUS.
493  *
494  * Does nothing if @hdl == NULL.
495  */
496 void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
497                                   const char *prefix);
498
499 /**
500  * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
501  *      control.
502  *
503  * @hdl:        The control handler.
504  * @cfg:        The control's configuration data.
505  * @priv:       The control's driver-specific private data.
506  *
507  * If the &v4l2_ctrl struct could not be allocated then NULL is returned
508  * and @hdl->error is set to the error code (if it wasn't set already).
509  */
510 struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
511                                        const struct v4l2_ctrl_config *cfg,
512                                        void *priv);
513
514 /**
515  * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu
516  *      control.
517  *
518  * @hdl:        The control handler.
519  * @ops:        The control ops.
520  * @id:         The control ID.
521  * @min:        The control's minimum value.
522  * @max:        The control's maximum value.
523  * @step:       The control's step value
524  * @def:        The control's default value.
525  *
526  * If the &v4l2_ctrl struct could not be allocated, or the control
527  * ID is not known, then NULL is returned and @hdl->error is set to the
528  * appropriate error code (if it wasn't set already).
529  *
530  * If @id refers to a menu control, then this function will return NULL.
531  *
532  * Use v4l2_ctrl_new_std_menu() when adding menu controls.
533  */
534 struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
535                                     const struct v4l2_ctrl_ops *ops,
536                                     u32 id, s64 min, s64 max, u64 step,
537                                     s64 def);
538
539 /**
540  * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2
541  *      menu control.
542  *
543  * @hdl:        The control handler.
544  * @ops:        The control ops.
545  * @id:         The control ID.
546  * @max:        The control's maximum value.
547  * @mask:       The control's skip mask for menu controls. This makes it
548  *              easy to skip menu items that are not valid. If bit X is set,
549  *              then menu item X is skipped. Of course, this only works for
550  *              menus with <= 64 menu items. There are no menus that come
551  *              close to that number, so this is OK. Should we ever need more,
552  *              then this will have to be extended to a bit array.
553  * @def:        The control's default value.
554  *
555  * Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value
556  * determines which menu items are to be skipped.
557  *
558  * If @id refers to a non-menu control, then this function will return NULL.
559  */
560 struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
561                                          const struct v4l2_ctrl_ops *ops,
562                                          u32 id, u8 max, u64 mask, u8 def);
563
564 /**
565  * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
566  *      with driver specific menu.
567  *
568  * @hdl:        The control handler.
569  * @ops:        The control ops.
570  * @id: The control ID.
571  * @max:        The control's maximum value.
572  * @mask:       The control's skip mask for menu controls. This makes it
573  *              easy to skip menu items that are not valid. If bit X is set,
574  *              then menu item X is skipped. Of course, this only works for
575  *              menus with <= 64 menu items. There are no menus that come
576  *              close to that number, so this is OK. Should we ever need more,
577  *              then this will have to be extended to a bit array.
578  * @def:        The control's default value.
579  * @qmenu:      The new menu.
580  *
581  * Same as v4l2_ctrl_new_std_menu(), but @qmenu will be the driver specific
582  * menu of this control.
583  *
584  */
585 struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl,
586                                                const struct v4l2_ctrl_ops *ops,
587                                                u32 id, u8 max,
588                                                u64 mask, u8 def,
589                                                const char * const *qmenu);
590
591 /**
592  * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
593  *
594  * @hdl:        The control handler.
595  * @ops:        The control ops.
596  * @id: The control ID.
597  * @max:        The control's maximum value.
598  * @def:        The control's default value.
599  * @qmenu_int:  The control's menu entries.
600  *
601  * Same as v4l2_ctrl_new_std_menu(), but @mask is set to 0 and it additionaly
602  * takes as an argument an array of integers determining the menu items.
603  *
604  * If @id refers to a non-integer-menu control, then this function will
605  * return %NULL.
606  */
607 struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
608                                          const struct v4l2_ctrl_ops *ops,
609                                          u32 id, u8 max, u8 def,
610                                          const s64 *qmenu_int);
611
612 /**
613  * typedef v4l2_ctrl_filter - Typedef to define the filter function to be
614  *      used when adding a control handler.
615  *
616  * @ctrl: pointer to struct &v4l2_ctrl.
617  */
618
619 typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl);
620
621 /**
622  * v4l2_ctrl_add_handler() - Add all controls from handler @add to
623  *      handler @hdl.
624  *
625  * @hdl:        The control handler.
626  * @add:        The control handler whose controls you want to add to
627  *              the @hdl control handler.
628  * @filter:     This function will filter which controls should be added.
629  *
630  * Does nothing if either of the two handlers is a NULL pointer.
631  * If @filter is NULL, then all controls are added. Otherwise only those
632  * controls for which @filter returns true will be added.
633  * In case of an error @hdl->error will be set to the error code (if it
634  * wasn't set already).
635  */
636 int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
637                           struct v4l2_ctrl_handler *add,
638                           v4l2_ctrl_filter filter);
639
640 /**
641  * v4l2_ctrl_radio_filter() - Standard filter for radio controls.
642  *
643  * @ctrl:       The control that is filtered.
644  *
645  * This will return true for any controls that are valid for radio device
646  * nodes. Those are all of the V4L2_CID_AUDIO_* user controls and all FM
647  * transmitter class controls.
648  *
649  * This function is to be used with v4l2_ctrl_add_handler().
650  */
651 bool v4l2_ctrl_radio_filter(const struct v4l2_ctrl *ctrl);
652
653 /**
654  * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging
655  *      to that cluster.
656  *
657  * @ncontrols:  The number of controls in this cluster.
658  * @controls:   The cluster control array of size @ncontrols.
659  */
660 void v4l2_ctrl_cluster(unsigned int ncontrols, struct v4l2_ctrl **controls);
661
662
663 /**
664  * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging
665  *      to that cluster and set it up for autofoo/foo-type handling.
666  *
667  * @ncontrols:  The number of controls in this cluster.
668  * @controls:   The cluster control array of size @ncontrols. The first control
669  *              must be the 'auto' control (e.g. autogain, autoexposure, etc.)
670  * @manual_val: The value for the first control in the cluster that equals the
671  *              manual setting.
672  * @set_volatile: If true, then all controls except the first auto control will
673  *              be volatile.
674  *
675  * Use for control groups where one control selects some automatic feature and
676  * the other controls are only active whenever the automatic feature is turned
677  * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
678  * red and blue balance, etc.
679  *
680  * The behavior of such controls is as follows:
681  *
682  * When the autofoo control is set to automatic, then any manual controls
683  * are set to inactive and any reads will call g_volatile_ctrl (if the control
684  * was marked volatile).
685  *
686  * When the autofoo control is set to manual, then any manual controls will
687  * be marked active, and any reads will just return the current value without
688  * going through g_volatile_ctrl.
689  *
690  * In addition, this function will set the %V4L2_CTRL_FLAG_UPDATE flag
691  * on the autofoo control and %V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
692  * if autofoo is in auto mode.
693  */
694 void v4l2_ctrl_auto_cluster(unsigned int ncontrols,
695                             struct v4l2_ctrl **controls,
696                             u8 manual_val, bool set_volatile);
697
698
699 /**
700  * v4l2_ctrl_find() - Find a control with the given ID.
701  *
702  * @hdl:        The control handler.
703  * @id: The control ID to find.
704  *
705  * If @hdl == NULL this will return NULL as well. Will lock the handler so
706  * do not use from inside &v4l2_ctrl_ops.
707  */
708 struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id);
709
710 /**
711  * v4l2_ctrl_activate() - Make the control active or inactive.
712  * @ctrl:       The control to (de)activate.
713  * @active:     True if the control should become active.
714  *
715  * This sets or clears the V4L2_CTRL_FLAG_INACTIVE flag atomically.
716  * Does nothing if @ctrl == NULL.
717  * This will usually be called from within the s_ctrl op.
718  * The V4L2_EVENT_CTRL event will be generated afterwards.
719  *
720  * This function assumes that the control handler is locked.
721  */
722 void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
723
724 /**
725  * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
726  *
727  * @ctrl:       The control to (de)activate.
728  * @grabbed:    True if the control should become grabbed.
729  *
730  * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically.
731  * Does nothing if @ctrl == NULL.
732  * The V4L2_EVENT_CTRL event will be generated afterwards.
733  * This will usually be called when starting or stopping streaming in the
734  * driver.
735  *
736  * This function assumes that the control handler is not locked and will
737  * take the lock itself.
738  */
739 void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed);
740
741 /**
742  *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
743  *
744  * @ctrl:       The control to update.
745  * @min:        The control's minimum value.
746  * @max:        The control's maximum value.
747  * @step:       The control's step value
748  * @def:        The control's default value.
749  *
750  * Update the range of a control on the fly. This works for control types
751  * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
752  * @step value is interpreted as a menu_skip_mask.
753  *
754  * An error is returned if one of the range arguments is invalid for this
755  * control type.
756  *
757  * This function assumes that the control handler is not locked and will
758  * take the lock itself.
759  */
760 int __v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
761                              s64 min, s64 max, u64 step, s64 def);
762
763 /**
764  * v4l2_ctrl_modify_range() - Update the range of a control.
765  *
766  * @ctrl:       The control to update.
767  * @min:        The control's minimum value.
768  * @max:        The control's maximum value.
769  * @step:       The control's step value
770  * @def:        The control's default value.
771  *
772  * Update the range of a control on the fly. This works for control types
773  * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
774  * @step value is interpreted as a menu_skip_mask.
775  *
776  * An error is returned if one of the range arguments is invalid for this
777  * control type.
778  *
779  * This function assumes that the control handler is not locked and will
780  * take the lock itself.
781  */
782 static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
783                                          s64 min, s64 max, u64 step, s64 def)
784 {
785         int rval;
786
787         v4l2_ctrl_lock(ctrl);
788         rval = __v4l2_ctrl_modify_range(ctrl, min, max, step, def);
789         v4l2_ctrl_unlock(ctrl);
790
791         return rval;
792 }
793
794 /**
795  * v4l2_ctrl_notify() - Function to set a notify callback for a control.
796  *
797  * @ctrl:       The control.
798  * @notify:     The callback function.
799  * @priv:       The callback private handle, passed as argument to the callback.
800  *
801  * This function sets a callback function for the control. If @ctrl is NULL,
802  * then it will do nothing. If @notify is NULL, then the notify callback will
803  * be removed.
804  *
805  * There can be only one notify. If another already exists, then a WARN_ON
806  * will be issued and the function will do nothing.
807  */
808 void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify,
809                       void *priv);
810
811 /**
812  * v4l2_ctrl_get_name() - Get the name of the control
813  *
814  * @id:         The control ID.
815  *
816  * This function returns the name of the given control ID or NULL if it isn't
817  * a known control.
818  */
819 const char *v4l2_ctrl_get_name(u32 id);
820
821 /**
822  * v4l2_ctrl_get_menu() - Get the menu string array of the control
823  *
824  * @id:         The control ID.
825  *
826  * This function returns the NULL-terminated menu string array name of the
827  * given control ID or NULL if it isn't a known menu control.
828  */
829 const char * const *v4l2_ctrl_get_menu(u32 id);
830
831 /**
832  * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
833  *
834  * @id:         The control ID.
835  * @len:        The size of the integer array.
836  *
837  * This function returns the integer array of the given control ID or NULL if it
838  * if it isn't a known integer menu control.
839  */
840 const s64 *v4l2_ctrl_get_int_menu(u32 id, u32 *len);
841
842 /**
843  * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from
844  *      within a driver.
845  *
846  * @ctrl:       The control.
847  *
848  * This returns the control's value safely by going through the control
849  * framework. This function will lock the control's handler, so it cannot be
850  * used from within the &v4l2_ctrl_ops functions.
851  *
852  * This function is for integer type controls only.
853  */
854 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
855
856 /**
857  * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
858  *
859  * @ctrl:       The control.
860  * @val:        TheControls name new value.
861  *
862  * This sets the control's new value safely by going through the control
863  * framework. This function assumes the control's handler is already locked,
864  * allowing it to be used from within the &v4l2_ctrl_ops functions.
865  *
866  * This function is for integer type controls only.
867  */
868 int __v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
869
870 /**
871  * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from
872  *      within a driver.
873  * @ctrl:       The control.
874  * @val:        The new value.
875  *
876  * This sets the control's new value safely by going through the control
877  * framework. This function will lock the control's handler, so it cannot be
878  * used from within the &v4l2_ctrl_ops functions.
879  *
880  * This function is for integer type controls only.
881  */
882 static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
883 {
884         int rval;
885
886         v4l2_ctrl_lock(ctrl);
887         rval = __v4l2_ctrl_s_ctrl(ctrl, val);
888         v4l2_ctrl_unlock(ctrl);
889
890         return rval;
891 }
892
893 /**
894  * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
895  *      from within a driver.
896  *
897  * @ctrl:       The control.
898  *
899  * This returns the control's value safely by going through the control
900  * framework. This function will lock the control's handler, so it cannot be
901  * used from within the &v4l2_ctrl_ops functions.
902  *
903  * This function is for 64-bit integer type controls only.
904  */
905 s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl);
906
907 /**
908  * __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64().
909  *
910  * @ctrl:       The control.
911  * @val:        The new value.
912  *
913  * This sets the control's new value safely by going through the control
914  * framework. This function assumes the control's handler is already locked,
915  * allowing it to be used from within the &v4l2_ctrl_ops functions.
916  *
917  * This function is for 64-bit integer type controls only.
918  */
919 int __v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val);
920
921 /**
922  * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
923  *      from within a driver.
924  *
925  * @ctrl:       The control.
926  * @val:        The new value.
927  *
928  * This sets the control's new value safely by going through the control
929  * framework. This function will lock the control's handler, so it cannot be
930  * used from within the &v4l2_ctrl_ops functions.
931  *
932  * This function is for 64-bit integer type controls only.
933  */
934 static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)
935 {
936         int rval;
937
938         v4l2_ctrl_lock(ctrl);
939         rval = __v4l2_ctrl_s_ctrl_int64(ctrl, val);
940         v4l2_ctrl_unlock(ctrl);
941
942         return rval;
943 }
944
945 /**
946  * __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
947  *
948  * @ctrl:       The control.
949  * @s:          The new string.
950  *
951  * This sets the control's new string safely by going through the control
952  * framework. This function assumes the control's handler is already locked,
953  * allowing it to be used from within the &v4l2_ctrl_ops functions.
954  *
955  * This function is for string type controls only.
956  */
957 int __v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s);
958
959 /**
960  * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
961  *       from within a driver.
962  *
963  * @ctrl:       The control.
964  * @s:          The new string.
965  *Controls name
966  * This sets the control's new string safely by going through the control
967  * framework. This function will lock the control's handler, so it cannot be
968  * used from within the &v4l2_ctrl_ops functions.
969  *
970  * This function is for string type controls only.
971  */
972 static inline int v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s)
973 {
974         int rval;
975
976         v4l2_ctrl_lock(ctrl);
977         rval = __v4l2_ctrl_s_ctrl_string(ctrl, s);
978         v4l2_ctrl_unlock(ctrl);
979
980         return rval;
981 }
982
983 /* Internal helper functions that deal with control events. */
984 extern const struct v4l2_subscribed_event_ops v4l2_ctrl_sub_ev_ops;
985
986 /**
987  * v4l2_ctrl_replace - Function to be used as a callback to
988  *      &struct v4l2_subscribed_event_ops replace\(\)
989  *
990  * @old: pointer to struct &v4l2_event with the reported
991  *       event;
992  * @new: pointer to struct &v4l2_event with the modified
993  *       event;
994  */
995 void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new);
996
997 /**
998  * v4l2_ctrl_merge - Function to be used as a callback to
999  *      &struct v4l2_subscribed_event_ops merge(\)
1000  *
1001  * @old: pointer to struct &v4l2_event with the reported
1002  *       event;
1003  * @new: pointer to struct &v4l2_event with the merged
1004  *       event;
1005  */
1006 void v4l2_ctrl_merge(const struct v4l2_event *old, struct v4l2_event *new);
1007
1008 /**
1009  * v4l2_ctrl_log_status - helper function to implement %VIDIOC_LOG_STATUS ioctl
1010  *
1011  * @file: pointer to struct file
1012  * @fh: unused. Kept just to be compatible to the arguments expected by
1013  *      &struct v4l2_ioctl_ops.vidioc_log_status.
1014  *
1015  * Can be used as a vidioc_log_status function that just dumps all controls
1016  * associated with the filehandle.
1017  */
1018 int v4l2_ctrl_log_status(struct file *file, void *fh);
1019
1020 /**
1021  * v4l2_ctrl_subscribe_event - Subscribes to an event
1022  *
1023  *
1024  * @fh: pointer to struct v4l2_fh
1025  * @sub: pointer to &struct v4l2_event_subscription
1026  *
1027  * Can be used as a vidioc_subscribe_event function that just subscribes
1028  * control events.
1029  */
1030 int v4l2_ctrl_subscribe_event(struct v4l2_fh *fh,
1031                                 const struct v4l2_event_subscription *sub);
1032
1033 /**
1034  * v4l2_ctrl_poll - function to be used as a callback to the poll()
1035  *      That just polls for control events.
1036  *
1037  * @file: pointer to struct file
1038  * @wait: pointer to struct poll_table_struct
1039  */
1040 unsigned int v4l2_ctrl_poll(struct file *file, struct poll_table_struct *wait);
1041
1042 /* Helpers for ioctl_ops */
1043
1044 /**
1045  * v4l2_queryctrl - Helper function to implement
1046  *      :ref:`VIDIOC_QUERYCTRL <vidioc_queryctrl>` ioctl
1047  *
1048  * @hdl: pointer to &struct v4l2_ctrl_handler
1049  * @qc: pointer to &struct v4l2_queryctrl
1050  *
1051  * If hdl == NULL then they will all return -EINVAL.
1052  */
1053 int v4l2_queryctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_queryctrl *qc);
1054
1055 /**
1056  * v4l2_query_ext_ctrl - Helper function to implement
1057  *       :ref:`VIDIOC_QUERY_EXT_CTRL <vidioc_queryctrl>` ioctl
1058  *
1059  * @hdl: pointer to &struct v4l2_ctrl_handler
1060  * @qc: pointer to &struct v4l2_query_ext_ctrl
1061  *
1062  * If hdl == NULL then they will all return -EINVAL.
1063  */
1064 int v4l2_query_ext_ctrl(struct v4l2_ctrl_handler *hdl,
1065                         struct v4l2_query_ext_ctrl *qc);
1066
1067 /**
1068  * v4l2_querymenu - Helper function to implement
1069  *      :ref:`VIDIOC_QUERYMENU <vidioc_queryctrl>` ioctl
1070  *
1071  * @hdl: pointer to &struct v4l2_ctrl_handler
1072  * @qm: pointer to &struct v4l2_querymenu
1073  *
1074  * If hdl == NULL then they will all return -EINVAL.
1075  */
1076 int v4l2_querymenu(struct v4l2_ctrl_handler *hdl, struct v4l2_querymenu *qm);
1077
1078 /**
1079  * v4l2_g_ctrl - Helper function to implement
1080  *      :ref:`VIDIOC_G_CTRL <vidioc_g_ctrl>` ioctl
1081  *
1082  * @hdl: pointer to &struct v4l2_ctrl_handler
1083  * @ctrl: pointer to &struct v4l2_control
1084  *
1085  * If hdl == NULL then they will all return -EINVAL.
1086  */
1087 int v4l2_g_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *ctrl);
1088
1089 /**
1090  * v4l2_s_ctrl - Helper function to implement
1091  *      :ref:`VIDIOC_S_CTRL <vidioc_g_ctrl>` ioctl
1092  *
1093  * @fh: pointer to &struct v4l2_fh
1094  * @hdl: pointer to &struct v4l2_ctrl_handler
1095  *
1096  * @ctrl: pointer to &struct v4l2_control
1097  *
1098  * If hdl == NULL then they will all return -EINVAL.
1099  */
1100 int v4l2_s_ctrl(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
1101                 struct v4l2_control *ctrl);
1102
1103 /**
1104  * v4l2_g_ext_ctrls - Helper function to implement
1105  *      :ref:`VIDIOC_G_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1106  *
1107  * @hdl: pointer to &struct v4l2_ctrl_handler
1108  * @c: pointer to &struct v4l2_ext_controls
1109  *
1110  * If hdl == NULL then they will all return -EINVAL.
1111  */
1112 int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl,
1113                      struct v4l2_ext_controls *c);
1114
1115 /**
1116  * v4l2_try_ext_ctrls - Helper function to implement
1117  *      :ref:`VIDIOC_TRY_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1118  *
1119  * @hdl: pointer to &struct v4l2_ctrl_handler
1120  * @c: pointer to &struct v4l2_ext_controls
1121  *
1122  * If hdl == NULL then they will all return -EINVAL.
1123  */
1124 int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl,
1125                        struct v4l2_ext_controls *c);
1126
1127 /**
1128  * v4l2_s_ext_ctrls - Helper function to implement
1129  *      :ref:`VIDIOC_S_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1130  *
1131  * @fh: pointer to &struct v4l2_fh
1132  * @hdl: pointer to &struct v4l2_ctrl_handler
1133  * @c: pointer to &struct v4l2_ext_controls
1134  *
1135  * If hdl == NULL then they will all return -EINVAL.
1136  */
1137 int v4l2_s_ext_ctrls(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
1138                      struct v4l2_ext_controls *c);
1139
1140 /**
1141  * v4l2_ctrl_subdev_subscribe_event - Helper function to implement
1142  *      as a &struct v4l2_subdev_core_ops subscribe_event function
1143  *      that just subscribes control events.
1144  *
1145  * @sd: pointer to &struct v4l2_subdev
1146  * @fh: pointer to &struct v4l2_fh
1147  * @sub: pointer to &struct v4l2_event_subscription
1148  */
1149 int v4l2_ctrl_subdev_subscribe_event(struct v4l2_subdev *sd, struct v4l2_fh *fh,
1150                                      struct v4l2_event_subscription *sub);
1151
1152 /**
1153  * v4l2_ctrl_subdev_log_status - Log all controls owned by subdev's control
1154  *       handler.
1155  *
1156  * @sd: pointer to &struct v4l2_subdev
1157  */
1158 int v4l2_ctrl_subdev_log_status(struct v4l2_subdev *sd);
1159
1160 #endif