~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/include/media/v4l2-ctrls.h

Version: ~ [ linux-5.9 ] ~ [ linux-5.8.14 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.70 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.150 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.200 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.238 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.238 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.52 ] ~ [ linux-4.0.9 ] ~ [ linux-3.19.8 ] ~ [ linux-3.18.140 ] ~ [ linux-3.17.8 ] ~ [ linux-3.16.85 ] ~ [ linux-3.15.10 ] ~ [ linux-3.14.79 ] ~ [ linux-3.13.11 ] ~ [ linux-3.12.74 ] ~ [ linux-3.11.10 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.5 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

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

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | Wiki (Japanese) | Wiki (English) | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

osdn.jp