1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 /*
3  *  V4L2 controls support header.
4  *
5  *  Copyright (C) 2010  Hans Verkuil <hverkuil@xs4all.nl>
6  */
7 
8 #ifndef _V4L2_CTRLS_H
9 #define _V4L2_CTRLS_H
10 
11 #include <linux/list.h>
12 #include <linux/mutex.h>
13 #include <linux/videodev2.h>
14 #include <media/media-request.h>
15 
16 /*
17  * Include the stateless codec compound control definitions.
18  * This will move to the public headers once this API is fully stable.
19  */
20 #include <media/hevc-ctrls.h>
21 
22 /* forward references */
23 struct file;
24 struct poll_table_struct;
25 struct v4l2_ctrl;
26 struct v4l2_ctrl_handler;
27 struct v4l2_ctrl_helper;
28 struct v4l2_fh;
29 struct v4l2_fwnode_device_properties;
30 struct v4l2_subdev;
31 struct v4l2_subscribed_event;
32 struct video_device;
33 
34 /**
35  * union v4l2_ctrl_ptr - A pointer to a control value.
36  * @p_s32:			Pointer to a 32-bit signed value.
37  * @p_s64:			Pointer to a 64-bit signed value.
38  * @p_u8:			Pointer to a 8-bit unsigned value.
39  * @p_u16:			Pointer to a 16-bit unsigned value.
40  * @p_u32:			Pointer to a 32-bit unsigned value.
41  * @p_char:			Pointer to a string.
42  * @p_mpeg2_sequence:		Pointer to a MPEG2 sequence structure.
43  * @p_mpeg2_picture:		Pointer to a MPEG2 picture structure.
44  * @p_mpeg2_quantisation:	Pointer to a MPEG2 quantisation data structure.
45  * @p_fwht_params:		Pointer to a FWHT stateless parameters structure.
46  * @p_h264_sps:			Pointer to a struct v4l2_ctrl_h264_sps.
47  * @p_h264_pps:			Pointer to a struct v4l2_ctrl_h264_pps.
48  * @p_h264_scaling_matrix:	Pointer to a struct v4l2_ctrl_h264_scaling_matrix.
49  * @p_h264_slice_params:	Pointer to a struct v4l2_ctrl_h264_slice_params.
50  * @p_h264_decode_params:	Pointer to a struct v4l2_ctrl_h264_decode_params.
51  * @p_h264_pred_weights:	Pointer to a struct v4l2_ctrl_h264_pred_weights.
52  * @p_vp8_frame:		Pointer to a VP8 frame params structure.
53  * @p_vp9_compressed_hdr_probs:	Pointer to a VP9 frame compressed header probs structure.
54  * @p_vp9_frame:		Pointer to a VP9 frame params structure.
55  * @p_hevc_sps:			Pointer to an HEVC sequence parameter set structure.
56  * @p_hevc_pps:			Pointer to an HEVC picture parameter set structure.
57  * @p_hevc_slice_params:	Pointer to an HEVC slice parameters structure.
58  * @p_hdr10_cll:		Pointer to an HDR10 Content Light Level structure.
59  * @p_hdr10_mastering:		Pointer to an HDR10 Mastering Display structure.
60  * @p_area:			Pointer to an area.
61  * @p:				Pointer to a compound value.
62  * @p_const:			Pointer to a constant compound value.
63  */
64 union v4l2_ctrl_ptr {
65 	s32 *p_s32;
66 	s64 *p_s64;
67 	u8 *p_u8;
68 	u16 *p_u16;
69 	u32 *p_u32;
70 	char *p_char;
71 	struct v4l2_ctrl_mpeg2_sequence *p_mpeg2_sequence;
72 	struct v4l2_ctrl_mpeg2_picture *p_mpeg2_picture;
73 	struct v4l2_ctrl_mpeg2_quantisation *p_mpeg2_quantisation;
74 	struct v4l2_ctrl_fwht_params *p_fwht_params;
75 	struct v4l2_ctrl_h264_sps *p_h264_sps;
76 	struct v4l2_ctrl_h264_pps *p_h264_pps;
77 	struct v4l2_ctrl_h264_scaling_matrix *p_h264_scaling_matrix;
78 	struct v4l2_ctrl_h264_slice_params *p_h264_slice_params;
79 	struct v4l2_ctrl_h264_decode_params *p_h264_decode_params;
80 	struct v4l2_ctrl_h264_pred_weights *p_h264_pred_weights;
81 	struct v4l2_ctrl_vp8_frame *p_vp8_frame;
82 	struct v4l2_ctrl_hevc_sps *p_hevc_sps;
83 	struct v4l2_ctrl_hevc_pps *p_hevc_pps;
84 	struct v4l2_ctrl_hevc_slice_params *p_hevc_slice_params;
85 	struct v4l2_ctrl_vp9_compressed_hdr *p_vp9_compressed_hdr_probs;
86 	struct v4l2_ctrl_vp9_frame *p_vp9_frame;
87 	struct v4l2_ctrl_hdr10_cll_info *p_hdr10_cll;
88 	struct v4l2_ctrl_hdr10_mastering_display *p_hdr10_mastering;
89 	struct v4l2_area *p_area;
90 	void *p;
91 	const void *p_const;
92 };
93 
94 /**
95  * v4l2_ctrl_ptr_create() - Helper function to return a v4l2_ctrl_ptr from a
96  * void pointer
97  * @ptr:	The void pointer
98  */
v4l2_ctrl_ptr_create(void * ptr)99 static inline union v4l2_ctrl_ptr v4l2_ctrl_ptr_create(void *ptr)
100 {
101 	union v4l2_ctrl_ptr p = { .p = ptr };
102 
103 	return p;
104 }
105 
106 /**
107  * struct v4l2_ctrl_ops - The control operations that the driver has to provide.
108  *
109  * @g_volatile_ctrl: Get a new value for this control. Generally only relevant
110  *		for volatile (and usually read-only) controls such as a control
111  *		that returns the current signal strength which changes
112  *		continuously.
113  *		If not set, then the currently cached value will be returned.
114  * @try_ctrl:	Test whether the control's value is valid. Only relevant when
115  *		the usual min/max/step checks are not sufficient.
116  * @s_ctrl:	Actually set the new control value. s_ctrl is compulsory. The
117  *		ctrl->handler->lock is held when these ops are called, so no
118  *		one else can access controls owned by that handler.
119  */
120 struct v4l2_ctrl_ops {
121 	int (*g_volatile_ctrl)(struct v4l2_ctrl *ctrl);
122 	int (*try_ctrl)(struct v4l2_ctrl *ctrl);
123 	int (*s_ctrl)(struct v4l2_ctrl *ctrl);
124 };
125 
126 /**
127  * struct v4l2_ctrl_type_ops - The control type operations that the driver
128  *			       has to provide.
129  *
130  * @equal: return true if both values are equal.
131  * @init: initialize the value.
132  * @log: log the value.
133  * @validate: validate the value. Return 0 on success and a negative value
134  *	otherwise.
135  */
136 struct v4l2_ctrl_type_ops {
137 	bool (*equal)(const struct v4l2_ctrl *ctrl, u32 idx,
138 		      union v4l2_ctrl_ptr ptr1,
139 		      union v4l2_ctrl_ptr ptr2);
140 	void (*init)(const struct v4l2_ctrl *ctrl, u32 idx,
141 		     union v4l2_ctrl_ptr ptr);
142 	void (*log)(const struct v4l2_ctrl *ctrl);
143 	int (*validate)(const struct v4l2_ctrl *ctrl, u32 idx,
144 			union v4l2_ctrl_ptr ptr);
145 };
146 
147 /**
148  * typedef v4l2_ctrl_notify_fnc - typedef for a notify argument with a function
149  *	that should be called when a control value has changed.
150  *
151  * @ctrl: pointer to struct &v4l2_ctrl
152  * @priv: control private data
153  *
154  * This typedef definition is used as an argument to v4l2_ctrl_notify()
155  * and as an argument at struct &v4l2_ctrl_handler.
156  */
157 typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
158 
159 /**
160  * struct v4l2_ctrl - The control structure.
161  *
162  * @node:	The list node.
163  * @ev_subs:	The list of control event subscriptions.
164  * @handler:	The handler that owns the control.
165  * @cluster:	Point to start of cluster array.
166  * @ncontrols:	Number of controls in cluster array.
167  * @done:	Internal flag: set for each processed control.
168  * @is_new:	Set when the user specified a new value for this control. It
169  *		is also set when called from v4l2_ctrl_handler_setup(). Drivers
170  *		should never set this flag.
171  * @has_changed: Set when the current value differs from the new value. Drivers
172  *		should never use this flag.
173  * @is_private: If set, then this control is private to its handler and it
174  *		will not be added to any other handlers. Drivers can set
175  *		this flag.
176  * @is_auto:   If set, then this control selects whether the other cluster
177  *		members are in 'automatic' mode or 'manual' mode. This is
178  *		used for autogain/gain type clusters. Drivers should never
179  *		set this flag directly.
180  * @is_int:    If set, then this control has a simple integer value (i.e. it
181  *		uses ctrl->val).
182  * @is_string: If set, then this control has type %V4L2_CTRL_TYPE_STRING.
183  * @is_ptr:	If set, then this control is an array and/or has type >=
184  *		%V4L2_CTRL_COMPOUND_TYPES
185  *		and/or has type %V4L2_CTRL_TYPE_STRING. In other words, &struct
186  *		v4l2_ext_control uses field p to point to the data.
187  * @is_array: If set, then this control contains an N-dimensional array.
188  * @has_volatiles: If set, then one or more members of the cluster are volatile.
189  *		Drivers should never touch this flag.
190  * @call_notify: If set, then call the handler's notify function whenever the
191  *		control's value changes.
192  * @manual_mode_value: If the is_auto flag is set, then this is the value
193  *		of the auto control that determines if that control is in
194  *		manual mode. So if the value of the auto control equals this
195  *		value, then the whole cluster is in manual mode. Drivers should
196  *		never set this flag directly.
197  * @ops:	The control ops.
198  * @type_ops:	The control type ops.
199  * @id:	The control ID.
200  * @name:	The control name.
201  * @type:	The control type.
202  * @minimum:	The control's minimum value.
203  * @maximum:	The control's maximum value.
204  * @default_value: The control's default value.
205  * @step:	The control's step value for non-menu controls.
206  * @elems:	The number of elements in the N-dimensional array.
207  * @elem_size:	The size in bytes of the control.
208  * @dims:	The size of each dimension.
209  * @nr_of_dims:The number of dimensions in @dims.
210  * @menu_skip_mask: The control's skip mask for menu controls. This makes it
211  *		easy to skip menu items that are not valid. If bit X is set,
212  *		then menu item X is skipped. Of course, this only works for
213  *		menus with <= 32 menu items. There are no menus that come
214  *		close to that number, so this is OK. Should we ever need more,
215  *		then this will have to be extended to a u64 or a bit array.
216  * @qmenu:	A const char * array for all menu items. Array entries that are
217  *		empty strings ("") correspond to non-existing menu items (this
218  *		is in addition to the menu_skip_mask above). The last entry
219  *		must be NULL.
220  *		Used only if the @type is %V4L2_CTRL_TYPE_MENU.
221  * @qmenu_int:	A 64-bit integer array for with integer menu items.
222  *		The size of array must be equal to the menu size, e. g.:
223  *		:math:`ceil(\frac{maximum - minimum}{step}) + 1`.
224  *		Used only if the @type is %V4L2_CTRL_TYPE_INTEGER_MENU.
225  * @flags:	The control's flags.
226  * @cur:	Structure to store the current value.
227  * @cur.val:	The control's current value, if the @type is represented via
228  *		a u32 integer (see &enum v4l2_ctrl_type).
229  * @val:	The control's new s32 value.
230  * @priv:	The control's private pointer. For use by the driver. It is
231  *		untouched by the control framework. Note that this pointer is
232  *		not freed when the control is deleted. Should this be needed
233  *		then a new internal bitfield can be added to tell the framework
234  *		to free this pointer.
235  * @p_def:	The control's default value represented via a union which
236  *		provides a standard way of accessing control types
237  *		through a pointer (for compound controls only).
238  * @p_cur:	The control's current value represented via a union which
239  *		provides a standard way of accessing control types
240  *		through a pointer.
241  * @p_new:	The control's new value represented via a union which provides
242  *		a standard way of accessing control types
243  *		through a pointer.
244  */
245 struct v4l2_ctrl {
246 	/* Administrative fields */
247 	struct list_head node;
248 	struct list_head ev_subs;
249 	struct v4l2_ctrl_handler *handler;
250 	struct v4l2_ctrl **cluster;
251 	unsigned int ncontrols;
252 
253 	unsigned int done:1;
254 
255 	unsigned int is_new:1;
256 	unsigned int has_changed:1;
257 	unsigned int is_private:1;
258 	unsigned int is_auto:1;
259 	unsigned int is_int:1;
260 	unsigned int is_string:1;
261 	unsigned int is_ptr:1;
262 	unsigned int is_array:1;
263 	unsigned int has_volatiles:1;
264 	unsigned int call_notify:1;
265 	unsigned int manual_mode_value:8;
266 
267 	const struct v4l2_ctrl_ops *ops;
268 	const struct v4l2_ctrl_type_ops *type_ops;
269 	u32 id;
270 	const char *name;
271 	enum v4l2_ctrl_type type;
272 	s64 minimum, maximum, default_value;
273 	u32 elems;
274 	u32 elem_size;
275 	u32 dims[V4L2_CTRL_MAX_DIMS];
276 	u32 nr_of_dims;
277 	union {
278 		u64 step;
279 		u64 menu_skip_mask;
280 	};
281 	union {
282 		const char * const *qmenu;
283 		const s64 *qmenu_int;
284 	};
285 	unsigned long flags;
286 	void *priv;
287 	s32 val;
288 	struct {
289 		s32 val;
290 	} cur;
291 
292 	union v4l2_ctrl_ptr p_def;
293 	union v4l2_ctrl_ptr p_new;
294 	union v4l2_ctrl_ptr p_cur;
295 };
296 
297 /**
298  * struct v4l2_ctrl_ref - The control reference.
299  *
300  * @node:	List node for the sorted list.
301  * @next:	Single-link list node for the hash.
302  * @ctrl:	The actual control information.
303  * @helper:	Pointer to helper struct. Used internally in
304  *		``prepare_ext_ctrls`` function at ``v4l2-ctrl.c``.
305  * @from_other_dev: If true, then @ctrl was defined in another
306  *		device than the &struct v4l2_ctrl_handler.
307  * @req_done:	Internal flag: if the control handler containing this control
308  *		reference is bound to a media request, then this is set when
309  *		the control has been applied. This prevents applying controls
310  *		from a cluster with multiple controls twice (when the first
311  *		control of a cluster is applied, they all are).
312  * @valid_p_req: If set, then p_req contains the control value for the request.
313  * @p_req:	If the control handler containing this control reference
314  *		is bound to a media request, then this points to the
315  *		value of the control that must be applied when the request
316  *		is executed, or to the value of the control at the time
317  *		that the request was completed. If @valid_p_req is false,
318  *		then this control was never set for this request and the
319  *		control will not be updated when this request is applied.
320  *
321  * Each control handler has a list of these refs. The list_head is used to
322  * keep a sorted-by-control-ID list of all controls, while the next pointer
323  * is used to link the control in the hash's bucket.
324  */
325 struct v4l2_ctrl_ref {
326 	struct list_head node;
327 	struct v4l2_ctrl_ref *next;
328 	struct v4l2_ctrl *ctrl;
329 	struct v4l2_ctrl_helper *helper;
330 	bool from_other_dev;
331 	bool req_done;
332 	bool valid_p_req;
333 	union v4l2_ctrl_ptr p_req;
334 };
335 
336 /**
337  * struct v4l2_ctrl_handler - The control handler keeps track of all the
338  *	controls: both the controls owned by the handler and those inherited
339  *	from other handlers.
340  *
341  * @_lock:	Default for "lock".
342  * @lock:	Lock to control access to this handler and its controls.
343  *		May be replaced by the user right after init.
344  * @ctrls:	The list of controls owned by this handler.
345  * @ctrl_refs:	The list of control references.
346  * @cached:	The last found control reference. It is common that the same
347  *		control is needed multiple times, so this is a simple
348  *		optimization.
349  * @buckets:	Buckets for the hashing. Allows for quick control lookup.
350  * @notify:	A notify callback that is called whenever the control changes
351  *		value.
352  *		Note that the handler's lock is held when the notify function
353  *		is called!
354  * @notify_priv: Passed as argument to the v4l2_ctrl notify callback.
355  * @nr_of_buckets: Total number of buckets in the array.
356  * @error:	The error code of the first failed control addition.
357  * @request_is_queued: True if the request was queued.
358  * @requests:	List to keep track of open control handler request objects.
359  *		For the parent control handler (@req_obj.ops == NULL) this
360  *		is the list header. When the parent control handler is
361  *		removed, it has to unbind and put all these requests since
362  *		they refer to the parent.
363  * @requests_queued: List of the queued requests. This determines the order
364  *		in which these controls are applied. Once the request is
365  *		completed it is removed from this list.
366  * @req_obj:	The &struct media_request_object, used to link into a
367  *		&struct media_request. This request object has a refcount.
368  */
369 struct v4l2_ctrl_handler {
370 	struct mutex _lock;
371 	struct mutex *lock;
372 	struct list_head ctrls;
373 	struct list_head ctrl_refs;
374 	struct v4l2_ctrl_ref *cached;
375 	struct v4l2_ctrl_ref **buckets;
376 	v4l2_ctrl_notify_fnc notify;
377 	void *notify_priv;
378 	u16 nr_of_buckets;
379 	int error;
380 	bool request_is_queued;
381 	struct list_head requests;
382 	struct list_head requests_queued;
383 	struct media_request_object req_obj;
384 };
385 
386 /**
387  * struct v4l2_ctrl_config - Control configuration structure.
388  *
389  * @ops:	The control ops.
390  * @type_ops:	The control type ops. Only needed for compound controls.
391  * @id:	The control ID.
392  * @name:	The control name.
393  * @type:	The control type.
394  * @min:	The control's minimum value.
395  * @max:	The control's maximum value.
396  * @step:	The control's step value for non-menu controls.
397  * @def:	The control's default value.
398  * @p_def:	The control's default value for compound controls.
399  * @dims:	The size of each dimension.
400  * @elem_size:	The size in bytes of the control.
401  * @flags:	The control's flags.
402  * @menu_skip_mask: The control's skip mask for menu controls. This makes it
403  *		easy to skip menu items that are not valid. If bit X is set,
404  *		then menu item X is skipped. Of course, this only works for
405  *		menus with <= 64 menu items. There are no menus that come
406  *		close to that number, so this is OK. Should we ever need more,
407  *		then this will have to be extended to a bit array.
408  * @qmenu:	A const char * array for all menu items. Array entries that are
409  *		empty strings ("") correspond to non-existing menu items (this
410  *		is in addition to the menu_skip_mask above). The last entry
411  *		must be NULL.
412  * @qmenu_int:	A const s64 integer array for all menu items of the type
413  *		V4L2_CTRL_TYPE_INTEGER_MENU.
414  * @is_private: If set, then this control is private to its handler and it
415  *		will not be added to any other handlers.
416  */
417 struct v4l2_ctrl_config {
418 	const struct v4l2_ctrl_ops *ops;
419 	const struct v4l2_ctrl_type_ops *type_ops;
420 	u32 id;
421 	const char *name;
422 	enum v4l2_ctrl_type type;
423 	s64 min;
424 	s64 max;
425 	u64 step;
426 	s64 def;
427 	union v4l2_ctrl_ptr p_def;
428 	u32 dims[V4L2_CTRL_MAX_DIMS];
429 	u32 elem_size;
430 	u32 flags;
431 	u64 menu_skip_mask;
432 	const char * const *qmenu;
433 	const s64 *qmenu_int;
434 	unsigned int is_private:1;
435 };
436 
437 /**
438  * v4l2_ctrl_fill - Fill in the control fields based on the control ID.
439  *
440  * @id: ID of the control
441  * @name: pointer to be filled with a string with the name of the control
442  * @type: pointer for storing the type of the control
443  * @min: pointer for storing the minimum value for the control
444  * @max: pointer for storing the maximum value for the control
445  * @step: pointer for storing the control step
446  * @def: pointer for storing the default value for the control
447  * @flags: pointer for storing the flags to be used on the control
448  *
449  * This works for all standard V4L2 controls.
450  * For non-standard controls it will only fill in the given arguments
451  * and @name content will be set to %NULL.
452  *
453  * This function will overwrite the contents of @name, @type and @flags.
454  * The contents of @min, @max, @step and @def may be modified depending on
455  * the type.
456  *
457  * .. note::
458  *
459  *    Do not use in drivers! It is used internally for backwards compatibility
460  *    control handling only. Once all drivers are converted to use the new
461  *    control framework this function will no longer be exported.
462  */
463 void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
464 		    s64 *min, s64 *max, u64 *step, s64 *def, u32 *flags);
465 
466 
467 /**
468  * v4l2_ctrl_handler_init_class() - Initialize the control handler.
469  * @hdl:	The control handler.
470  * @nr_of_controls_hint: A hint of how many controls this handler is
471  *		expected to refer to. This is the total number, so including
472  *		any inherited controls. It doesn't have to be precise, but if
473  *		it is way off, then you either waste memory (too many buckets
474  *		are allocated) or the control lookup becomes slower (not enough
475  *		buckets are allocated, so there are more slow list lookups).
476  *		It will always work, though.
477  * @key:	Used by the lock validator if CONFIG_LOCKDEP is set.
478  * @name:	Used by the lock validator if CONFIG_LOCKDEP is set.
479  *
480  * .. attention::
481  *
482  *    Never use this call directly, always use the v4l2_ctrl_handler_init()
483  *    macro that hides the @key and @name arguments.
484  *
485  * Return: returns an error if the buckets could not be allocated. This
486  * error will also be stored in @hdl->error.
487  */
488 int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
489 				 unsigned int nr_of_controls_hint,
490 				 struct lock_class_key *key, const char *name);
491 
492 #ifdef CONFIG_LOCKDEP
493 
494 /**
495  * v4l2_ctrl_handler_init - helper function to create a static struct
496  *	 &lock_class_key and calls v4l2_ctrl_handler_init_class()
497  *
498  * @hdl:	The control handler.
499  * @nr_of_controls_hint: A hint of how many controls this handler is
500  *		expected to refer to. This is the total number, so including
501  *		any inherited controls. It doesn't have to be precise, but if
502  *		it is way off, then you either waste memory (too many buckets
503  *		are allocated) or the control lookup becomes slower (not enough
504  *		buckets are allocated, so there are more slow list lookups).
505  *		It will always work, though.
506  *
507  * This helper function creates a static struct &lock_class_key and
508  * calls v4l2_ctrl_handler_init_class(), providing a proper name for the lock
509  * validador.
510  *
511  * Use this helper function to initialize a control handler.
512  */
513 #define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint)		\
514 (									\
515 	({								\
516 		static struct lock_class_key _key;			\
517 		v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint,	\
518 					&_key,				\
519 					KBUILD_BASENAME ":"		\
520 					__stringify(__LINE__) ":"	\
521 					"(" #hdl ")->_lock");		\
522 	})								\
523 )
524 #else
525 #define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint)		\
526 	v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint, NULL, NULL)
527 #endif
528 
529 /**
530  * v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
531  * the control list.
532  * @hdl:	The control handler.
533  *
534  * Does nothing if @hdl == NULL.
535  */
536 void v4l2_ctrl_handler_free(struct v4l2_ctrl_handler *hdl);
537 
538 /**
539  * v4l2_ctrl_lock() - Helper function to lock the handler
540  * associated with the control.
541  * @ctrl:	The control to lock.
542  */
v4l2_ctrl_lock(struct v4l2_ctrl * ctrl)543 static inline void v4l2_ctrl_lock(struct v4l2_ctrl *ctrl)
544 {
545 	mutex_lock(ctrl->handler->lock);
546 }
547 
548 /**
549  * v4l2_ctrl_unlock() - Helper function to unlock the handler
550  * associated with the control.
551  * @ctrl:	The control to unlock.
552  */
v4l2_ctrl_unlock(struct v4l2_ctrl * ctrl)553 static inline void v4l2_ctrl_unlock(struct v4l2_ctrl *ctrl)
554 {
555 	mutex_unlock(ctrl->handler->lock);
556 }
557 
558 /**
559  * __v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
560  * to the handler to initialize the hardware to the current control values. The
561  * caller is responsible for acquiring the control handler mutex on behalf of
562  * __v4l2_ctrl_handler_setup().
563  * @hdl:	The control handler.
564  *
565  * Button controls will be skipped, as are read-only controls.
566  *
567  * If @hdl == NULL, then this just returns 0.
568  */
569 int __v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
570 
571 /**
572  * v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
573  * to the handler to initialize the hardware to the current control values.
574  * @hdl:	The control handler.
575  *
576  * Button controls will be skipped, as are read-only controls.
577  *
578  * If @hdl == NULL, then this just returns 0.
579  */
580 int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
581 
582 /**
583  * v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
584  * @hdl:	The control handler.
585  * @prefix:	The prefix to use when logging the control values. If the
586  *		prefix does not end with a space, then ": " will be added
587  *		after the prefix. If @prefix == NULL, then no prefix will be
588  *		used.
589  *
590  * For use with VIDIOC_LOG_STATUS.
591  *
592  * Does nothing if @hdl == NULL.
593  */
594 void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
595 				  const char *prefix);
596 
597 /**
598  * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
599  *	control.
600  *
601  * @hdl:	The control handler.
602  * @cfg:	The control's configuration data.
603  * @priv:	The control's driver-specific private data.
604  *
605  * If the &v4l2_ctrl struct could not be allocated then NULL is returned
606  * and @hdl->error is set to the error code (if it wasn't set already).
607  */
608 struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
609 				       const struct v4l2_ctrl_config *cfg,
610 				       void *priv);
611 
612 /**
613  * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu
614  *	control.
615  *
616  * @hdl:	The control handler.
617  * @ops:	The control ops.
618  * @id:		The control ID.
619  * @min:	The control's minimum value.
620  * @max:	The control's maximum value.
621  * @step:	The control's step value
622  * @def:	The control's default value.
623  *
624  * If the &v4l2_ctrl struct could not be allocated, or the control
625  * ID is not known, then NULL is returned and @hdl->error is set to the
626  * appropriate error code (if it wasn't set already).
627  *
628  * If @id refers to a menu control, then this function will return NULL.
629  *
630  * Use v4l2_ctrl_new_std_menu() when adding menu controls.
631  */
632 struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
633 				    const struct v4l2_ctrl_ops *ops,
634 				    u32 id, s64 min, s64 max, u64 step,
635 				    s64 def);
636 
637 /**
638  * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2
639  *	menu control.
640  *
641  * @hdl:	The control handler.
642  * @ops:	The control ops.
643  * @id:		The control ID.
644  * @max:	The control's maximum value.
645  * @mask:	The control's skip mask for menu controls. This makes it
646  *		easy to skip menu items that are not valid. If bit X is set,
647  *		then menu item X is skipped. Of course, this only works for
648  *		menus with <= 64 menu items. There are no menus that come
649  *		close to that number, so this is OK. Should we ever need more,
650  *		then this will have to be extended to a bit array.
651  * @def:	The control's default value.
652  *
653  * Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value
654  * determines which menu items are to be skipped.
655  *
656  * If @id refers to a non-menu control, then this function will return NULL.
657  */
658 struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
659 					 const struct v4l2_ctrl_ops *ops,
660 					 u32 id, u8 max, u64 mask, u8 def);
661 
662 /**
663  * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
664  *	with driver specific menu.
665  *
666  * @hdl:	The control handler.
667  * @ops:	The control ops.
668  * @id:	The control ID.
669  * @max:	The control's maximum value.
670  * @mask:	The control's skip mask for menu controls. This makes it
671  *		easy to skip menu items that are not valid. If bit X is set,
672  *		then menu item X is skipped. Of course, this only works for
673  *		menus with <= 64 menu items. There are no menus that come
674  *		close to that number, so this is OK. Should we ever need more,
675  *		then this will have to be extended to a bit array.
676  * @def:	The control's default value.
677  * @qmenu:	The new menu.
678  *
679  * Same as v4l2_ctrl_new_std_menu(), but @qmenu will be the driver specific
680  * menu of this control.
681  *
682  */
683 struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl,
684 					       const struct v4l2_ctrl_ops *ops,
685 					       u32 id, u8 max,
686 					       u64 mask, u8 def,
687 					       const char * const *qmenu);
688 
689 /**
690  * v4l2_ctrl_new_std_compound() - Allocate and initialize a new standard V4L2
691  *      compound control.
692  *
693  * @hdl:       The control handler.
694  * @ops:       The control ops.
695  * @id:        The control ID.
696  * @p_def:     The control's default value.
697  *
698  * Sames as v4l2_ctrl_new_std(), but with support to compound controls, thanks
699  * to the @p_def field. Use v4l2_ctrl_ptr_create() to create @p_def from a
700  * pointer. Use v4l2_ctrl_ptr_create(NULL) if the default value of the
701  * compound control should be all zeroes.
702  *
703  */
704 struct v4l2_ctrl *v4l2_ctrl_new_std_compound(struct v4l2_ctrl_handler *hdl,
705 					     const struct v4l2_ctrl_ops *ops,
706 					     u32 id,
707 					     const union v4l2_ctrl_ptr p_def);
708 
709 /**
710  * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
711  *
712  * @hdl:	The control handler.
713  * @ops:	The control ops.
714  * @id:	The control ID.
715  * @max:	The control's maximum value.
716  * @def:	The control's default value.
717  * @qmenu_int:	The control's menu entries.
718  *
719  * Same as v4l2_ctrl_new_std_menu(), but @mask is set to 0 and it additionally
720  * takes as an argument an array of integers determining the menu items.
721  *
722  * If @id refers to a non-integer-menu control, then this function will
723  * return %NULL.
724  */
725 struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
726 					 const struct v4l2_ctrl_ops *ops,
727 					 u32 id, u8 max, u8 def,
728 					 const s64 *qmenu_int);
729 
730 /**
731  * typedef v4l2_ctrl_filter - Typedef to define the filter function to be
732  *	used when adding a control handler.
733  *
734  * @ctrl: pointer to struct &v4l2_ctrl.
735  */
736 
737 typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl);
738 
739 /**
740  * v4l2_ctrl_add_handler() - Add all controls from handler @add to
741  *	handler @hdl.
742  *
743  * @hdl:	The control handler.
744  * @add:	The control handler whose controls you want to add to
745  *		the @hdl control handler.
746  * @filter:	This function will filter which controls should be added.
747  * @from_other_dev: If true, then the controls in @add were defined in another
748  *		device than @hdl.
749  *
750  * Does nothing if either of the two handlers is a NULL pointer.
751  * If @filter is NULL, then all controls are added. Otherwise only those
752  * controls for which @filter returns true will be added.
753  * In case of an error @hdl->error will be set to the error code (if it
754  * wasn't set already).
755  */
756 int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
757 			  struct v4l2_ctrl_handler *add,
758 			  v4l2_ctrl_filter filter,
759 			  bool from_other_dev);
760 
761 /**
762  * v4l2_ctrl_radio_filter() - Standard filter for radio controls.
763  *
764  * @ctrl:	The control that is filtered.
765  *
766  * This will return true for any controls that are valid for radio device
767  * nodes. Those are all of the V4L2_CID_AUDIO_* user controls and all FM
768  * transmitter class controls.
769  *
770  * This function is to be used with v4l2_ctrl_add_handler().
771  */
772 bool v4l2_ctrl_radio_filter(const struct v4l2_ctrl *ctrl);
773 
774 /**
775  * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging
776  *	to that cluster.
777  *
778  * @ncontrols:	The number of controls in this cluster.
779  * @controls:	The cluster control array of size @ncontrols.
780  */
781 void v4l2_ctrl_cluster(unsigned int ncontrols, struct v4l2_ctrl **controls);
782 
783 
784 /**
785  * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging
786  *	to that cluster and set it up for autofoo/foo-type handling.
787  *
788  * @ncontrols:	The number of controls in this cluster.
789  * @controls:	The cluster control array of size @ncontrols. The first control
790  *		must be the 'auto' control (e.g. autogain, autoexposure, etc.)
791  * @manual_val: The value for the first control in the cluster that equals the
792  *		manual setting.
793  * @set_volatile: If true, then all controls except the first auto control will
794  *		be volatile.
795  *
796  * Use for control groups where one control selects some automatic feature and
797  * the other controls are only active whenever the automatic feature is turned
798  * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
799  * red and blue balance, etc.
800  *
801  * The behavior of such controls is as follows:
802  *
803  * When the autofoo control is set to automatic, then any manual controls
804  * are set to inactive and any reads will call g_volatile_ctrl (if the control
805  * was marked volatile).
806  *
807  * When the autofoo control is set to manual, then any manual controls will
808  * be marked active, and any reads will just return the current value without
809  * going through g_volatile_ctrl.
810  *
811  * In addition, this function will set the %V4L2_CTRL_FLAG_UPDATE flag
812  * on the autofoo control and %V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
813  * if autofoo is in auto mode.
814  */
815 void v4l2_ctrl_auto_cluster(unsigned int ncontrols,
816 			    struct v4l2_ctrl **controls,
817 			    u8 manual_val, bool set_volatile);
818 
819 
820 /**
821  * v4l2_ctrl_find() - Find a control with the given ID.
822  *
823  * @hdl:	The control handler.
824  * @id:	The control ID to find.
825  *
826  * If @hdl == NULL this will return NULL as well. Will lock the handler so
827  * do not use from inside &v4l2_ctrl_ops.
828  */
829 struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id);
830 
831 /**
832  * v4l2_ctrl_activate() - Make the control active or inactive.
833  * @ctrl:	The control to (de)activate.
834  * @active:	True if the control should become active.
835  *
836  * This sets or clears the V4L2_CTRL_FLAG_INACTIVE flag atomically.
837  * Does nothing if @ctrl == NULL.
838  * This will usually be called from within the s_ctrl op.
839  * The V4L2_EVENT_CTRL event will be generated afterwards.
840  *
841  * This function assumes that the control handler is locked.
842  */
843 void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
844 
845 /**
846  * __v4l2_ctrl_grab() - Unlocked variant of v4l2_ctrl_grab.
847  *
848  * @ctrl:	The control to (de)activate.
849  * @grabbed:	True if the control should become grabbed.
850  *
851  * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically.
852  * Does nothing if @ctrl == NULL.
853  * The V4L2_EVENT_CTRL event will be generated afterwards.
854  * This will usually be called when starting or stopping streaming in the
855  * driver.
856  *
857  * This function assumes that the control handler is locked by the caller.
858  */
859 void __v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed);
860 
861 /**
862  * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
863  *
864  * @ctrl:	The control to (de)activate.
865  * @grabbed:	True if the control should become grabbed.
866  *
867  * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically.
868  * Does nothing if @ctrl == NULL.
869  * The V4L2_EVENT_CTRL event will be generated afterwards.
870  * This will usually be called when starting or stopping streaming in the
871  * driver.
872  *
873  * This function assumes that the control handler is not locked and will
874  * take the lock itself.
875  */
v4l2_ctrl_grab(struct v4l2_ctrl * ctrl,bool grabbed)876 static inline void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed)
877 {
878 	if (!ctrl)
879 		return;
880 
881 	v4l2_ctrl_lock(ctrl);
882 	__v4l2_ctrl_grab(ctrl, grabbed);
883 	v4l2_ctrl_unlock(ctrl);
884 }
885 
886 /**
887  *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
888  *
889  * @ctrl:	The control to update.
890  * @min:	The control's minimum value.
891  * @max:	The control's maximum value.
892  * @step:	The control's step value
893  * @def:	The control's default value.
894  *
895  * Update the range of a control on the fly. This works for control types
896  * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
897  * @step value is interpreted as a menu_skip_mask.
898  *
899  * An error is returned if one of the range arguments is invalid for this
900  * control type.
901  *
902  * The caller is responsible for acquiring the control handler mutex on behalf
903  * of __v4l2_ctrl_modify_range().
904  */
905 int __v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
906 			     s64 min, s64 max, u64 step, s64 def);
907 
908 /**
909  * v4l2_ctrl_modify_range() - Update the range of a control.
910  *
911  * @ctrl:	The control to update.
912  * @min:	The control's minimum value.
913  * @max:	The control's maximum value.
914  * @step:	The control's step value
915  * @def:	The control's default value.
916  *
917  * Update the range of a control on the fly. This works for control types
918  * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
919  * @step value is interpreted as a menu_skip_mask.
920  *
921  * An error is returned if one of the range arguments is invalid for this
922  * control type.
923  *
924  * This function assumes that the control handler is not locked and will
925  * take the lock itself.
926  */
v4l2_ctrl_modify_range(struct v4l2_ctrl * ctrl,s64 min,s64 max,u64 step,s64 def)927 static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
928 					 s64 min, s64 max, u64 step, s64 def)
929 {
930 	int rval;
931 
932 	v4l2_ctrl_lock(ctrl);
933 	rval = __v4l2_ctrl_modify_range(ctrl, min, max, step, def);
934 	v4l2_ctrl_unlock(ctrl);
935 
936 	return rval;
937 }
938 
939 /**
940  * v4l2_ctrl_notify() - Function to set a notify callback for a control.
941  *
942  * @ctrl:	The control.
943  * @notify:	The callback function.
944  * @priv:	The callback private handle, passed as argument to the callback.
945  *
946  * This function sets a callback function for the control. If @ctrl is NULL,
947  * then it will do nothing. If @notify is NULL, then the notify callback will
948  * be removed.
949  *
950  * There can be only one notify. If another already exists, then a WARN_ON
951  * will be issued and the function will do nothing.
952  */
953 void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify,
954 		      void *priv);
955 
956 /**
957  * v4l2_ctrl_get_name() - Get the name of the control
958  *
959  * @id:		The control ID.
960  *
961  * This function returns the name of the given control ID or NULL if it isn't
962  * a known control.
963  */
964 const char *v4l2_ctrl_get_name(u32 id);
965 
966 /**
967  * v4l2_ctrl_get_menu() - Get the menu string array of the control
968  *
969  * @id:		The control ID.
970  *
971  * This function returns the NULL-terminated menu string array name of the
972  * given control ID or NULL if it isn't a known menu control.
973  */
974 const char * const *v4l2_ctrl_get_menu(u32 id);
975 
976 /**
977  * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
978  *
979  * @id:		The control ID.
980  * @len:	The size of the integer array.
981  *
982  * This function returns the integer array of the given control ID or NULL if it
983  * if it isn't a known integer menu control.
984  */
985 const s64 *v4l2_ctrl_get_int_menu(u32 id, u32 *len);
986 
987 /**
988  * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from
989  *	within a driver.
990  *
991  * @ctrl:	The control.
992  *
993  * This returns the control's value safely by going through the control
994  * framework. This function will lock the control's handler, so it cannot be
995  * used from within the &v4l2_ctrl_ops functions.
996  *
997  * This function is for integer type controls only.
998  */
999 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
1000 
1001 /**
1002  * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
1003  *
1004  * @ctrl:	The control.
1005  * @val:	The new value.
1006  *
1007  * This sets the control's new value safely by going through the control
1008  * framework. This function assumes the control's handler is already locked,
1009  * allowing it to be used from within the &v4l2_ctrl_ops functions.
1010  *
1011  * This function is for integer type controls only.
1012  */
1013 int __v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
1014 
1015 /**
1016  * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from
1017  *	within a driver.
1018  * @ctrl:	The control.
1019  * @val:	The new value.
1020  *
1021  * This sets the control's new value safely by going through the control
1022  * framework. This function will lock the control's handler, so it cannot be
1023  * used from within the &v4l2_ctrl_ops functions.
1024  *
1025  * This function is for integer type controls only.
1026  */
v4l2_ctrl_s_ctrl(struct v4l2_ctrl * ctrl,s32 val)1027 static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
1028 {
1029 	int rval;
1030 
1031 	v4l2_ctrl_lock(ctrl);
1032 	rval = __v4l2_ctrl_s_ctrl(ctrl, val);
1033 	v4l2_ctrl_unlock(ctrl);
1034 
1035 	return rval;
1036 }
1037 
1038 /**
1039  * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
1040  *	from within a driver.
1041  *
1042  * @ctrl:	The control.
1043  *
1044  * This returns the control's value safely by going through the control
1045  * framework. This function will lock the control's handler, so it cannot be
1046  * used from within the &v4l2_ctrl_ops functions.
1047  *
1048  * This function is for 64-bit integer type controls only.
1049  */
1050 s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl);
1051 
1052 /**
1053  * __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64().
1054  *
1055  * @ctrl:	The control.
1056  * @val:	The new value.
1057  *
1058  * This sets the control's new value safely by going through the control
1059  * framework. This function assumes the control's handler is already locked,
1060  * allowing it to be used from within the &v4l2_ctrl_ops functions.
1061  *
1062  * This function is for 64-bit integer type controls only.
1063  */
1064 int __v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val);
1065 
1066 /**
1067  * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
1068  *	from within a driver.
1069  *
1070  * @ctrl:	The control.
1071  * @val:	The new value.
1072  *
1073  * This sets the control's new value safely by going through the control
1074  * framework. This function will lock the control's handler, so it cannot be
1075  * used from within the &v4l2_ctrl_ops functions.
1076  *
1077  * This function is for 64-bit integer type controls only.
1078  */
v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl * ctrl,s64 val)1079 static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)
1080 {
1081 	int rval;
1082 
1083 	v4l2_ctrl_lock(ctrl);
1084 	rval = __v4l2_ctrl_s_ctrl_int64(ctrl, val);
1085 	v4l2_ctrl_unlock(ctrl);
1086 
1087 	return rval;
1088 }
1089 
1090 /**
1091  * __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
1092  *
1093  * @ctrl:	The control.
1094  * @s:		The new string.
1095  *
1096  * This sets the control's new string safely by going through the control
1097  * framework. This function assumes the control's handler is already locked,
1098  * allowing it to be used from within the &v4l2_ctrl_ops functions.
1099  *
1100  * This function is for string type controls only.
1101  */
1102 int __v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s);
1103 
1104 /**
1105  * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
1106  *	 from within a driver.
1107  *
1108  * @ctrl:	The control.
1109  * @s:		The new string.
1110  *
1111  * This sets the control's new string safely by going through the control
1112  * framework. This function will lock the control's handler, so it cannot be
1113  * used from within the &v4l2_ctrl_ops functions.
1114  *
1115  * This function is for string type controls only.
1116  */
v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl * ctrl,const char * s)1117 static inline int v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s)
1118 {
1119 	int rval;
1120 
1121 	v4l2_ctrl_lock(ctrl);
1122 	rval = __v4l2_ctrl_s_ctrl_string(ctrl, s);
1123 	v4l2_ctrl_unlock(ctrl);
1124 
1125 	return rval;
1126 }
1127 
1128 /**
1129  * __v4l2_ctrl_s_ctrl_compound() - Unlocked variant to set a compound control
1130  *
1131  * @ctrl: The control.
1132  * @type: The type of the data.
1133  * @p:    The new compound payload.
1134  *
1135  * This sets the control's new compound payload safely by going through the
1136  * control framework. This function assumes the control's handler is already
1137  * locked, allowing it to be used from within the &v4l2_ctrl_ops functions.
1138  *
1139  * This function is for compound type controls only.
1140  */
1141 int __v4l2_ctrl_s_ctrl_compound(struct v4l2_ctrl *ctrl,
1142 				enum v4l2_ctrl_type type, const void *p);
1143 
1144 /**
1145  * v4l2_ctrl_s_ctrl_compound() - Helper function to set a compound control
1146  *	from within a driver.
1147  *
1148  * @ctrl: The control.
1149  * @type: The type of the data.
1150  * @p:    The new compound payload.
1151  *
1152  * This sets the control's new compound payload safely by going through the
1153  * control framework. This function will lock the control's handler, so it
1154  * cannot be used from within the &v4l2_ctrl_ops functions.
1155  *
1156  * This function is for compound type controls only.
1157  */
v4l2_ctrl_s_ctrl_compound(struct v4l2_ctrl * ctrl,enum v4l2_ctrl_type type,const void * p)1158 static inline int v4l2_ctrl_s_ctrl_compound(struct v4l2_ctrl *ctrl,
1159 					    enum v4l2_ctrl_type type,
1160 					    const void *p)
1161 {
1162 	int rval;
1163 
1164 	v4l2_ctrl_lock(ctrl);
1165 	rval = __v4l2_ctrl_s_ctrl_compound(ctrl, type, p);
1166 	v4l2_ctrl_unlock(ctrl);
1167 
1168 	return rval;
1169 }
1170 
1171 /* Helper defines for area type controls */
1172 #define __v4l2_ctrl_s_ctrl_area(ctrl, area) \
1173 	__v4l2_ctrl_s_ctrl_compound((ctrl), V4L2_CTRL_TYPE_AREA, (area))
1174 #define v4l2_ctrl_s_ctrl_area(ctrl, area) \
1175 	v4l2_ctrl_s_ctrl_compound((ctrl), V4L2_CTRL_TYPE_AREA, (area))
1176 
1177 /* Internal helper functions that deal with control events. */
1178 extern const struct v4l2_subscribed_event_ops v4l2_ctrl_sub_ev_ops;
1179 
1180 /**
1181  * v4l2_ctrl_replace - Function to be used as a callback to
1182  *	&struct v4l2_subscribed_event_ops replace\(\)
1183  *
1184  * @old: pointer to struct &v4l2_event with the reported
1185  *	 event;
1186  * @new: pointer to struct &v4l2_event with the modified
1187  *	 event;
1188  */
1189 void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new);
1190 
1191 /**
1192  * v4l2_ctrl_merge - Function to be used as a callback to
1193  *	&struct v4l2_subscribed_event_ops merge(\)
1194  *
1195  * @old: pointer to struct &v4l2_event with the reported
1196  *	 event;
1197  * @new: pointer to struct &v4l2_event with the merged
1198  *	 event;
1199  */
1200 void v4l2_ctrl_merge(const struct v4l2_event *old, struct v4l2_event *new);
1201 
1202 /**
1203  * v4l2_ctrl_log_status - helper function to implement %VIDIOC_LOG_STATUS ioctl
1204  *
1205  * @file: pointer to struct file
1206  * @fh: unused. Kept just to be compatible to the arguments expected by
1207  *	&struct v4l2_ioctl_ops.vidioc_log_status.
1208  *
1209  * Can be used as a vidioc_log_status function that just dumps all controls
1210  * associated with the filehandle.
1211  */
1212 int v4l2_ctrl_log_status(struct file *file, void *fh);
1213 
1214 /**
1215  * v4l2_ctrl_subscribe_event - Subscribes to an event
1216  *
1217  *
1218  * @fh: pointer to struct v4l2_fh
1219  * @sub: pointer to &struct v4l2_event_subscription
1220  *
1221  * Can be used as a vidioc_subscribe_event function that just subscribes
1222  * control events.
1223  */
1224 int v4l2_ctrl_subscribe_event(struct v4l2_fh *fh,
1225 				const struct v4l2_event_subscription *sub);
1226 
1227 /**
1228  * v4l2_ctrl_poll - function to be used as a callback to the poll()
1229  *	That just polls for control events.
1230  *
1231  * @file: pointer to struct file
1232  * @wait: pointer to struct poll_table_struct
1233  */
1234 __poll_t v4l2_ctrl_poll(struct file *file, struct poll_table_struct *wait);
1235 
1236 /**
1237  * v4l2_ctrl_request_setup - helper function to apply control values in a request
1238  *
1239  * @req: The request
1240  * @parent: The parent control handler ('priv' in media_request_object_find())
1241  *
1242  * This is a helper function to call the control handler's s_ctrl callback with
1243  * the control values contained in the request. Do note that this approach of
1244  * applying control values in a request is only applicable to memory-to-memory
1245  * devices.
1246  */
1247 int v4l2_ctrl_request_setup(struct media_request *req,
1248 			     struct v4l2_ctrl_handler *parent);
1249 
1250 /**
1251  * v4l2_ctrl_request_complete - Complete a control handler request object
1252  *
1253  * @req: The request
1254  * @parent: The parent control handler ('priv' in media_request_object_find())
1255  *
1256  * This function is to be called on each control handler that may have had a
1257  * request object associated with it, i.e. control handlers of a driver that
1258  * supports requests.
1259  *
1260  * The function first obtains the values of any volatile controls in the control
1261  * handler and attach them to the request. Then, the function completes the
1262  * request object.
1263  */
1264 void v4l2_ctrl_request_complete(struct media_request *req,
1265 				struct v4l2_ctrl_handler *parent);
1266 
1267 /**
1268  * v4l2_ctrl_request_hdl_find - Find the control handler in the request
1269  *
1270  * @req: The request
1271  * @parent: The parent control handler ('priv' in media_request_object_find())
1272  *
1273  * This function finds the control handler in the request. It may return
1274  * NULL if not found. When done, you must call v4l2_ctrl_request_put_hdl()
1275  * with the returned handler pointer.
1276  *
1277  * If the request is not in state VALIDATING or QUEUED, then this function
1278  * will always return NULL.
1279  *
1280  * Note that in state VALIDATING the req_queue_mutex is held, so
1281  * no objects can be added or deleted from the request.
1282  *
1283  * In state QUEUED it is the driver that will have to ensure this.
1284  */
1285 struct v4l2_ctrl_handler *v4l2_ctrl_request_hdl_find(struct media_request *req,
1286 					struct v4l2_ctrl_handler *parent);
1287 
1288 /**
1289  * v4l2_ctrl_request_hdl_put - Put the control handler
1290  *
1291  * @hdl: Put this control handler
1292  *
1293  * This function released the control handler previously obtained from'
1294  * v4l2_ctrl_request_hdl_find().
1295  */
v4l2_ctrl_request_hdl_put(struct v4l2_ctrl_handler * hdl)1296 static inline void v4l2_ctrl_request_hdl_put(struct v4l2_ctrl_handler *hdl)
1297 {
1298 	if (hdl)
1299 		media_request_object_put(&hdl->req_obj);
1300 }
1301 
1302 /**
1303  * v4l2_ctrl_request_hdl_ctrl_find() - Find a control with the given ID.
1304  *
1305  * @hdl: The control handler from the request.
1306  * @id: The ID of the control to find.
1307  *
1308  * This function returns a pointer to the control if this control is
1309  * part of the request or NULL otherwise.
1310  */
1311 struct v4l2_ctrl *
1312 v4l2_ctrl_request_hdl_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id);
1313 
1314 /* Helpers for ioctl_ops */
1315 
1316 /**
1317  * v4l2_queryctrl - Helper function to implement
1318  *	:ref:`VIDIOC_QUERYCTRL <vidioc_queryctrl>` ioctl
1319  *
1320  * @hdl: pointer to &struct v4l2_ctrl_handler
1321  * @qc: pointer to &struct v4l2_queryctrl
1322  *
1323  * If hdl == NULL then they will all return -EINVAL.
1324  */
1325 int v4l2_queryctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_queryctrl *qc);
1326 
1327 /**
1328  * v4l2_query_ext_ctrl - Helper function to implement
1329  *	 :ref:`VIDIOC_QUERY_EXT_CTRL <vidioc_queryctrl>` ioctl
1330  *
1331  * @hdl: pointer to &struct v4l2_ctrl_handler
1332  * @qc: pointer to &struct v4l2_query_ext_ctrl
1333  *
1334  * If hdl == NULL then they will all return -EINVAL.
1335  */
1336 int v4l2_query_ext_ctrl(struct v4l2_ctrl_handler *hdl,
1337 			struct v4l2_query_ext_ctrl *qc);
1338 
1339 /**
1340  * v4l2_querymenu - Helper function to implement
1341  *	:ref:`VIDIOC_QUERYMENU <vidioc_queryctrl>` ioctl
1342  *
1343  * @hdl: pointer to &struct v4l2_ctrl_handler
1344  * @qm: pointer to &struct v4l2_querymenu
1345  *
1346  * If hdl == NULL then they will all return -EINVAL.
1347  */
1348 int v4l2_querymenu(struct v4l2_ctrl_handler *hdl, struct v4l2_querymenu *qm);
1349 
1350 /**
1351  * v4l2_g_ctrl - Helper function to implement
1352  *	:ref:`VIDIOC_G_CTRL <vidioc_g_ctrl>` ioctl
1353  *
1354  * @hdl: pointer to &struct v4l2_ctrl_handler
1355  * @ctrl: pointer to &struct v4l2_control
1356  *
1357  * If hdl == NULL then they will all return -EINVAL.
1358  */
1359 int v4l2_g_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *ctrl);
1360 
1361 /**
1362  * v4l2_s_ctrl - Helper function to implement
1363  *	:ref:`VIDIOC_S_CTRL <vidioc_g_ctrl>` ioctl
1364  *
1365  * @fh: pointer to &struct v4l2_fh
1366  * @hdl: pointer to &struct v4l2_ctrl_handler
1367  *
1368  * @ctrl: pointer to &struct v4l2_control
1369  *
1370  * If hdl == NULL then they will all return -EINVAL.
1371  */
1372 int v4l2_s_ctrl(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
1373 		struct v4l2_control *ctrl);
1374 
1375 /**
1376  * v4l2_g_ext_ctrls - Helper function to implement
1377  *	:ref:`VIDIOC_G_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1378  *
1379  * @hdl: pointer to &struct v4l2_ctrl_handler
1380  * @vdev: pointer to &struct video_device
1381  * @mdev: pointer to &struct media_device
1382  * @c: pointer to &struct v4l2_ext_controls
1383  *
1384  * If hdl == NULL then they will all return -EINVAL.
1385  */
1386 int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct video_device *vdev,
1387 		     struct media_device *mdev, struct v4l2_ext_controls *c);
1388 
1389 /**
1390  * v4l2_try_ext_ctrls - Helper function to implement
1391  *	:ref:`VIDIOC_TRY_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1392  *
1393  * @hdl: pointer to &struct v4l2_ctrl_handler
1394  * @vdev: pointer to &struct video_device
1395  * @mdev: pointer to &struct media_device
1396  * @c: pointer to &struct v4l2_ext_controls
1397  *
1398  * If hdl == NULL then they will all return -EINVAL.
1399  */
1400 int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl,
1401 		       struct video_device *vdev,
1402 		       struct media_device *mdev,
1403 		       struct v4l2_ext_controls *c);
1404 
1405 /**
1406  * v4l2_s_ext_ctrls - Helper function to implement
1407  *	:ref:`VIDIOC_S_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1408  *
1409  * @fh: pointer to &struct v4l2_fh
1410  * @hdl: pointer to &struct v4l2_ctrl_handler
1411  * @vdev: pointer to &struct video_device
1412  * @mdev: pointer to &struct media_device
1413  * @c: pointer to &struct v4l2_ext_controls
1414  *
1415  * If hdl == NULL then they will all return -EINVAL.
1416  */
1417 int v4l2_s_ext_ctrls(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
1418 		     struct video_device *vdev,
1419 		     struct media_device *mdev,
1420 		     struct v4l2_ext_controls *c);
1421 
1422 /**
1423  * v4l2_ctrl_subdev_subscribe_event - Helper function to implement
1424  *	as a &struct v4l2_subdev_core_ops subscribe_event function
1425  *	that just subscribes control events.
1426  *
1427  * @sd: pointer to &struct v4l2_subdev
1428  * @fh: pointer to &struct v4l2_fh
1429  * @sub: pointer to &struct v4l2_event_subscription
1430  */
1431 int v4l2_ctrl_subdev_subscribe_event(struct v4l2_subdev *sd, struct v4l2_fh *fh,
1432 				     struct v4l2_event_subscription *sub);
1433 
1434 /**
1435  * v4l2_ctrl_subdev_log_status - Log all controls owned by subdev's control
1436  *	 handler.
1437  *
1438  * @sd: pointer to &struct v4l2_subdev
1439  */
1440 int v4l2_ctrl_subdev_log_status(struct v4l2_subdev *sd);
1441 
1442 /**
1443  * v4l2_ctrl_new_fwnode_properties() - Register controls for the device
1444  *				       properties
1445  *
1446  * @hdl: pointer to &struct v4l2_ctrl_handler to register controls on
1447  * @ctrl_ops: pointer to &struct v4l2_ctrl_ops to register controls with
1448  * @p: pointer to &struct v4l2_fwnode_device_properties
1449  *
1450  * This function registers controls associated to device properties, using the
1451  * property values contained in @p parameter, if the property has been set to
1452  * a value.
1453  *
1454  * Currently the following v4l2 controls are parsed and registered:
1455  * - V4L2_CID_CAMERA_ORIENTATION
1456  * - V4L2_CID_CAMERA_SENSOR_ROTATION;
1457  *
1458  * Controls already registered by the caller with the @hdl control handler are
1459  * not overwritten. Callers should register the controls they want to handle
1460  * themselves before calling this function.
1461  *
1462  * Return: 0 on success, a negative error code on failure.
1463  */
1464 int v4l2_ctrl_new_fwnode_properties(struct v4l2_ctrl_handler *hdl,
1465 				    const struct v4l2_ctrl_ops *ctrl_ops,
1466 				    const struct v4l2_fwnode_device_properties *p);
1467 #endif
1468