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