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