blob: bee1404391dd5565abe2d324f4a196f0602fc032 [file] [log] [blame]
Hans Verkuil09965172010-08-01 14:32:42 -03001/*
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -03002 * 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.
Hans Verkuil09965172010-08-01 14:32:42 -030015 */
16
17#ifndef _V4L2_CTRLS_H
18#define _V4L2_CTRLS_H
19
20#include <linux/list.h>
Andrzej Hajdaa19dec62013-06-28 05:44:22 -030021#include <linux/mutex.h>
Laurent Pinchart01c40c02010-11-19 11:20:06 -030022#include <linux/videodev2.h>
Hans Verkuil09965172010-08-01 14:32:42 -030023
24/* forward references */
Laurent Pinchart528f0f72012-04-23 08:20:35 -030025struct file;
Hans Verkuil09965172010-08-01 14:32:42 -030026struct v4l2_ctrl_handler;
Hans Verkuileb5b16e2011-06-14 10:04:06 -030027struct v4l2_ctrl_helper;
Hans Verkuil09965172010-08-01 14:32:42 -030028struct v4l2_ctrl;
29struct video_device;
30struct v4l2_subdev;
Hans Verkuil77068d32011-06-13 18:55:58 -030031struct v4l2_subscribed_event;
Hans Verkuil6e239392011-06-07 11:13:44 -030032struct v4l2_fh;
Hans Verkuila26243b2012-01-27 16:18:42 -030033struct poll_table_struct;
Hans Verkuil09965172010-08-01 14:32:42 -030034
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -030035/**
36 * union v4l2_ctrl_ptr - A pointer to a control value.
Hans Verkuil01760772014-04-27 03:22:17 -030037 * @p_s32: Pointer to a 32-bit signed value.
38 * @p_s64: Pointer to a 64-bit signed value.
Hans Verkuildda4a4d2014-06-10 07:30:04 -030039 * @p_u8: Pointer to a 8-bit unsigned value.
40 * @p_u16: Pointer to a 16-bit unsigned value.
Hans Verkuil811c5082014-07-21 10:45:37 -030041 * @p_u32: Pointer to a 32-bit unsigned value.
Hans Verkuil01760772014-04-27 03:22:17 -030042 * @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;
Hans Verkuildda4a4d2014-06-10 07:30:04 -030048 u8 *p_u8;
49 u16 *p_u16;
Hans Verkuil811c5082014-07-21 10:45:37 -030050 u32 *p_u32;
Hans Verkuil01760772014-04-27 03:22:17 -030051 char *p_char;
52 void *p;
53};
54
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -030055/**
56 * struct v4l2_ctrl_ops - The control operations that the driver has to provide.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -030057 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -030058 * @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 */
Hans Verkuil09965172010-08-01 14:32:42 -030069struct 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
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -030075/**
76 * struct v4l2_ctrl_type_ops - The control type operations that the driver
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -030077 * has to provide.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -030078 *
79 * @equal: return true if both values are equal.
80 * @init: initialize the value.
81 * @log: log the value.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -030082 * @validate: validate the value. Return 0 on success and a negative value
83 * otherwise.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -030084 */
Hans Verkuil01760772014-04-27 03:22:17 -030085struct v4l2_ctrl_type_ops {
Hans Verkuil998e7652014-06-10 07:55:00 -030086 bool (*equal)(const struct v4l2_ctrl *ctrl, u32 idx,
Hans Verkuil01760772014-04-27 03:22:17 -030087 union v4l2_ctrl_ptr ptr1,
88 union v4l2_ctrl_ptr ptr2);
Hans Verkuil998e7652014-06-10 07:55:00 -030089 void (*init)(const struct v4l2_ctrl *ctrl, u32 idx,
Hans Verkuil01760772014-04-27 03:22:17 -030090 union v4l2_ctrl_ptr ptr);
91 void (*log)(const struct v4l2_ctrl *ctrl);
Hans Verkuil998e7652014-06-10 07:55:00 -030092 int (*validate)(const struct v4l2_ctrl *ctrl, u32 idx,
Hans Verkuil01760772014-04-27 03:22:17 -030093 union v4l2_ctrl_ptr ptr);
94};
95
Mauro Carvalho Chehab2257e182016-08-29 17:26:15 -030096/**
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 */
Hans Verkuil8ac7a942012-09-07 04:46:39 -0300106typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
107
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300108/**
109 * struct v4l2_ctrl - The control structure.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300110 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300111 * @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
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300118 * is also set when called from v4l2_ctrl_handler_setup(). Drivers
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300119 * 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).
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300131 * @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
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300135 * v4l2_ext_control uses field p to point to the data.
136 * @is_array: If set, then this control contains an N-dimensional array.
137 * @has_volatiles: If set, then one or more members of the cluster are volatile.
138 * Drivers should never touch this flag.
139 * @call_notify: If set, then call the handler's notify function whenever the
140 * control's value changes.
141 * @manual_mode_value: If the is_auto flag is set, then this is the value
142 * of the auto control that determines if that control is in
143 * manual mode. So if the value of the auto control equals this
144 * value, then the whole cluster is in manual mode. Drivers should
145 * never set this flag directly.
146 * @ops: The control ops.
147 * @type_ops: The control type ops.
148 * @id: The control ID.
149 * @name: The control name.
150 * @type: The control type.
151 * @minimum: The control's minimum value.
152 * @maximum: The control's maximum value.
153 * @default_value: The control's default value.
154 * @step: The control's step value for non-menu controls.
155 * @elems: The number of elements in the N-dimensional array.
156 * @elem_size: The size in bytes of the control.
157 * @dims: The size of each dimension.
158 * @nr_of_dims:The number of dimensions in @dims.
159 * @menu_skip_mask: The control's skip mask for menu controls. This makes it
160 * easy to skip menu items that are not valid. If bit X is set,
161 * then menu item X is skipped. Of course, this only works for
162 * menus with <= 32 menu items. There are no menus that come
163 * close to that number, so this is OK. Should we ever need more,
164 * then this will have to be extended to a u64 or a bit array.
165 * @qmenu: A const char * array for all menu items. Array entries that are
166 * empty strings ("") correspond to non-existing menu items (this
167 * is in addition to the menu_skip_mask above). The last entry
168 * must be NULL.
169 * @flags: The control's flags.
170 * @cur: The control's current value.
171 * @val: The control's new s32 value.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300172 * @priv: The control's private pointer. For use by the driver. It is
173 * untouched by the control framework. Note that this pointer is
174 * not freed when the control is deleted. Should this be needed
175 * then a new internal bitfield can be added to tell the framework
176 * to free this pointer.
Masahiro Yamada03440c42017-02-27 14:28:49 -0800177 * @p_cur: The control's current value represented via a union with
Mauro Carvalho Chehab7dc87912015-08-22 08:22:03 -0300178 * provides a standard way of accessing control types
179 * through a pointer.
Masahiro Yamada03440c42017-02-27 14:28:49 -0800180 * @p_new: The control's new value represented via a union with provides
Mauro Carvalho Chehab7dc87912015-08-22 08:22:03 -0300181 * a standard way of accessing control types
182 * through a pointer.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300183 */
Hans Verkuil09965172010-08-01 14:32:42 -0300184struct v4l2_ctrl {
185 /* Administrative fields */
186 struct list_head node;
Hans Verkuil77068d32011-06-13 18:55:58 -0300187 struct list_head ev_subs;
Hans Verkuil09965172010-08-01 14:32:42 -0300188 struct v4l2_ctrl_handler *handler;
189 struct v4l2_ctrl **cluster;
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300190 unsigned int ncontrols;
191
Hans Verkuil09965172010-08-01 14:32:42 -0300192 unsigned int done:1;
193
Hans Verkuil2a863792011-01-11 14:45:03 -0300194 unsigned int is_new:1;
Hans Verkuil9ea1b7a2014-01-17 08:25:26 -0300195 unsigned int has_changed:1;
Hans Verkuil09965172010-08-01 14:32:42 -0300196 unsigned int is_private:1;
Hans Verkuil72d877c2011-06-10 05:44:36 -0300197 unsigned int is_auto:1;
Hans Verkuild9a25472014-06-12 07:54:16 -0300198 unsigned int is_int:1;
199 unsigned int is_string:1;
200 unsigned int is_ptr:1;
Hans Verkuil998e7652014-06-10 07:55:00 -0300201 unsigned int is_array:1;
Hans Verkuil5626b8c2011-08-26 07:53:53 -0300202 unsigned int has_volatiles:1;
Hans Verkuil8ac7a942012-09-07 04:46:39 -0300203 unsigned int call_notify:1;
Hans Verkuil82a7c042011-06-28 10:43:13 -0300204 unsigned int manual_mode_value:8;
Hans Verkuil09965172010-08-01 14:32:42 -0300205
206 const struct v4l2_ctrl_ops *ops;
Hans Verkuil01760772014-04-27 03:22:17 -0300207 const struct v4l2_ctrl_type_ops *type_ops;
Hans Verkuil09965172010-08-01 14:32:42 -0300208 u32 id;
209 const char *name;
210 enum v4l2_ctrl_type type;
Hans Verkuil0ba2aeb2014-04-16 09:41:25 -0300211 s64 minimum, maximum, default_value;
Hans Verkuil20d88ee2014-06-12 07:55:21 -0300212 u32 elems;
Hans Verkuild9a25472014-06-12 07:54:16 -0300213 u32 elem_size;
Hans Verkuil20d88ee2014-06-12 07:55:21 -0300214 u32 dims[V4L2_CTRL_MAX_DIMS];
215 u32 nr_of_dims;
Hans Verkuil09965172010-08-01 14:32:42 -0300216 union {
Hans Verkuil0ba2aeb2014-04-16 09:41:25 -0300217 u64 step;
218 u64 menu_skip_mask;
Hans Verkuil09965172010-08-01 14:32:42 -0300219 };
Sakari Ailusce580fe2011-08-04 13:51:11 -0300220 union {
221 const char * const *qmenu;
222 const s64 *qmenu_int;
223 };
Hans Verkuil09965172010-08-01 14:32:42 -0300224 unsigned long flags;
Hans Verkuil09965172010-08-01 14:32:42 -0300225 void *priv;
Hans Verkuil2a9ec372014-04-27 03:38:13 -0300226 s32 val;
227 struct {
Hans Verkuild9a25472014-06-12 07:54:16 -0300228 s32 val;
Hans Verkuild9a25472014-06-12 07:54:16 -0300229 } cur;
Hans Verkuil01760772014-04-27 03:22:17 -0300230
231 union v4l2_ctrl_ptr p_new;
232 union v4l2_ctrl_ptr p_cur;
Hans Verkuil09965172010-08-01 14:32:42 -0300233};
234
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300235/**
236 * struct v4l2_ctrl_ref - The control reference.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300237 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300238 * @node: List node for the sorted list.
239 * @next: Single-link list node for the hash.
240 * @ctrl: The actual control information.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300241 * @helper: Pointer to helper struct. Used internally in
Mauro Carvalho Chehabfb911612016-08-29 18:43:02 -0300242 * ``prepare_ext_ctrls`` function at ``v4l2-ctrl.c``.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300243 *
244 * Each control handler has a list of these refs. The list_head is used to
245 * keep a sorted-by-control-ID list of all controls, while the next pointer
246 * is used to link the control in the hash's bucket.
247 */
Hans Verkuil09965172010-08-01 14:32:42 -0300248struct v4l2_ctrl_ref {
249 struct list_head node;
250 struct v4l2_ctrl_ref *next;
251 struct v4l2_ctrl *ctrl;
Hans Verkuileb5b16e2011-06-14 10:04:06 -0300252 struct v4l2_ctrl_helper *helper;
Hans Verkuil09965172010-08-01 14:32:42 -0300253};
254
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300255/**
256 * struct v4l2_ctrl_handler - The control handler keeps track of all the
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300257 * controls: both the controls owned by the handler and those inherited
258 * from other handlers.
259 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300260 * @_lock: Default for "lock".
261 * @lock: Lock to control access to this handler and its controls.
262 * May be replaced by the user right after init.
263 * @ctrls: The list of controls owned by this handler.
264 * @ctrl_refs: The list of control references.
265 * @cached: The last found control reference. It is common that the same
266 * control is needed multiple times, so this is a simple
267 * optimization.
268 * @buckets: Buckets for the hashing. Allows for quick control lookup.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300269 * @notify: A notify callback that is called whenever the control changes
270 * value.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300271 * Note that the handler's lock is held when the notify function
272 * is called!
273 * @notify_priv: Passed as argument to the v4l2_ctrl notify callback.
274 * @nr_of_buckets: Total number of buckets in the array.
275 * @error: The error code of the first failed control addition.
276 */
Hans Verkuil09965172010-08-01 14:32:42 -0300277struct v4l2_ctrl_handler {
Sakari Ailus77e7c4e2012-01-24 21:05:34 -0300278 struct mutex _lock;
279 struct mutex *lock;
Hans Verkuil09965172010-08-01 14:32:42 -0300280 struct list_head ctrls;
281 struct list_head ctrl_refs;
282 struct v4l2_ctrl_ref *cached;
283 struct v4l2_ctrl_ref **buckets;
Hans Verkuil8ac7a942012-09-07 04:46:39 -0300284 v4l2_ctrl_notify_fnc notify;
285 void *notify_priv;
Hans Verkuil09965172010-08-01 14:32:42 -0300286 u16 nr_of_buckets;
287 int error;
288};
289
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300290/**
291 * struct v4l2_ctrl_config - Control configuration structure.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300292 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300293 * @ops: The control ops.
294 * @type_ops: The control type ops. Only needed for compound controls.
295 * @id: The control ID.
296 * @name: The control name.
297 * @type: The control type.
298 * @min: The control's minimum value.
299 * @max: The control's maximum value.
300 * @step: The control's step value for non-menu controls.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300301 * @def: The control's default value.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300302 * @dims: The size of each dimension.
303 * @elem_size: The size in bytes of the control.
304 * @flags: The control's flags.
305 * @menu_skip_mask: The control's skip mask for menu controls. This makes it
306 * easy to skip menu items that are not valid. If bit X is set,
307 * then menu item X is skipped. Of course, this only works for
308 * menus with <= 64 menu items. There are no menus that come
309 * close to that number, so this is OK. Should we ever need more,
310 * then this will have to be extended to a bit array.
311 * @qmenu: A const char * array for all menu items. Array entries that are
312 * empty strings ("") correspond to non-existing menu items (this
313 * is in addition to the menu_skip_mask above). The last entry
314 * must be NULL.
Mauro Carvalho Chehab7dc87912015-08-22 08:22:03 -0300315 * @qmenu_int: A const s64 integer array for all menu items of the type
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300316 * V4L2_CTRL_TYPE_INTEGER_MENU.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300317 * @is_private: If set, then this control is private to its handler and it
318 * will not be added to any other handlers.
319 */
Hans Verkuil09965172010-08-01 14:32:42 -0300320struct v4l2_ctrl_config {
321 const struct v4l2_ctrl_ops *ops;
Hans Verkuil01760772014-04-27 03:22:17 -0300322 const struct v4l2_ctrl_type_ops *type_ops;
Hans Verkuil09965172010-08-01 14:32:42 -0300323 u32 id;
324 const char *name;
325 enum v4l2_ctrl_type type;
Hans Verkuil0ba2aeb2014-04-16 09:41:25 -0300326 s64 min;
327 s64 max;
328 u64 step;
329 s64 def;
Hans Verkuil20d88ee2014-06-12 07:55:21 -0300330 u32 dims[V4L2_CTRL_MAX_DIMS];
Hans Verkuild9a25472014-06-12 07:54:16 -0300331 u32 elem_size;
Hans Verkuil09965172010-08-01 14:32:42 -0300332 u32 flags;
Hans Verkuil0ba2aeb2014-04-16 09:41:25 -0300333 u64 menu_skip_mask;
Hans Verkuil513521e2010-12-29 14:25:52 -0300334 const char * const *qmenu;
Sakari Ailusce580fe2011-08-04 13:51:11 -0300335 const s64 *qmenu_int;
Hans Verkuil09965172010-08-01 14:32:42 -0300336 unsigned int is_private:1;
Hans Verkuil09965172010-08-01 14:32:42 -0300337};
338
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300339/**
340 * v4l2_ctrl_fill - Fill in the control fields based on the control ID.
341 *
342 * @id: ID of the control
343 * @name: name of the control
344 * @type: type of the control
345 * @min: minimum value for the control
346 * @max: maximum value for the control
347 * @step: control step
348 * @def: default value for the control
349 * @flags: flags to be used on the control
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300350 *
351 * This works for all standard V4L2 controls.
352 * For non-standard controls it will only fill in the given arguments
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300353 * and @name will be %NULL.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300354 *
355 * This function will overwrite the contents of @name, @type and @flags.
356 * The contents of @min, @max, @step and @def may be modified depending on
357 * the type.
358 *
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300359 * .. note::
360 *
361 * Do not use in drivers! It is used internally for backwards compatibility
362 * control handling only. Once all drivers are converted to use the new
363 * control framework this function will no longer be exported.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300364 */
Hans Verkuil09965172010-08-01 14:32:42 -0300365void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
Hans Verkuil0ba2aeb2014-04-16 09:41:25 -0300366 s64 *min, s64 *max, u64 *step, s64 *def, u32 *flags);
Hans Verkuil09965172010-08-01 14:32:42 -0300367
368
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300369/**
370 * v4l2_ctrl_handler_init_class() - Initialize the control handler.
371 * @hdl: The control handler.
372 * @nr_of_controls_hint: A hint of how many controls this handler is
373 * expected to refer to. This is the total number, so including
374 * any inherited controls. It doesn't have to be precise, but if
375 * it is way off, then you either waste memory (too many buckets
376 * are allocated) or the control lookup becomes slower (not enough
377 * buckets are allocated, so there are more slow list lookups).
378 * It will always work, though.
379 * @key: Used by the lock validator if CONFIG_LOCKDEP is set.
380 * @name: Used by the lock validator if CONFIG_LOCKDEP is set.
381 *
Mauro Carvalho Chehab2257e182016-08-29 17:26:15 -0300382 * .. attention::
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300383 *
Mauro Carvalho Chehab2257e182016-08-29 17:26:15 -0300384 * Never use this call directly, always use the v4l2_ctrl_handler_init()
385 * macro that hides the @key and @name arguments.
386 *
387 * Return: returns an error if the buckets could not be allocated. This
388 * error will also be stored in @hdl->error.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300389 */
Andy Walls6cd247e2013-03-09 05:55:11 -0300390int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300391 unsigned int nr_of_controls_hint,
Andy Walls6cd247e2013-03-09 05:55:11 -0300392 struct lock_class_key *key, const char *name);
393
394#ifdef CONFIG_LOCKDEP
Mauro Carvalho Chehab2257e182016-08-29 17:26:15 -0300395
396/**
Mauro Carvalho Chehabe383ce02016-09-22 07:59:03 -0300397 * v4l2_ctrl_handler_init - helper function to create a static struct
398 * &lock_class_key and calls v4l2_ctrl_handler_init_class()
Mauro Carvalho Chehab2257e182016-08-29 17:26:15 -0300399 *
400 * @hdl: The control handler.
401 * @nr_of_controls_hint: A hint of how many controls this handler is
402 * expected to refer to. This is the total number, so including
403 * any inherited controls. It doesn't have to be precise, but if
404 * it is way off, then you either waste memory (too many buckets
405 * are allocated) or the control lookup becomes slower (not enough
406 * buckets are allocated, so there are more slow list lookups).
407 * It will always work, though.
408 *
409 * This helper function creates a static struct &lock_class_key and
410 * calls v4l2_ctrl_handler_init_class(), providing a proper name for the lock
411 * validador.
412 *
413 * Use this helper function to initialize a control handler.
414 */
Andy Walls6cd247e2013-03-09 05:55:11 -0300415#define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint) \
416( \
417 ({ \
418 static struct lock_class_key _key; \
419 v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint, \
420 &_key, \
421 KBUILD_BASENAME ":" \
422 __stringify(__LINE__) ":" \
423 "(" #hdl ")->_lock"); \
424 }) \
425)
426#else
427#define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint) \
428 v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint, NULL, NULL)
429#endif
Hans Verkuil09965172010-08-01 14:32:42 -0300430
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300431/**
432 * v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
433 * the control list.
434 * @hdl: The control handler.
435 *
436 * Does nothing if @hdl == NULL.
437 */
Hans Verkuil09965172010-08-01 14:32:42 -0300438void v4l2_ctrl_handler_free(struct v4l2_ctrl_handler *hdl);
439
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300440/**
441 * v4l2_ctrl_lock() - Helper function to lock the handler
442 * associated with the control.
443 * @ctrl: The control to lock.
444 */
Sakari Ailus605b3842014-06-12 13:09:39 -0300445static inline void v4l2_ctrl_lock(struct v4l2_ctrl *ctrl)
446{
447 mutex_lock(ctrl->handler->lock);
448}
449
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300450/**
451 * v4l2_ctrl_unlock() - Helper function to unlock the handler
452 * associated with the control.
453 * @ctrl: The control to unlock.
454 */
Sakari Ailus605b3842014-06-12 13:09:39 -0300455static inline void v4l2_ctrl_unlock(struct v4l2_ctrl *ctrl)
456{
457 mutex_unlock(ctrl->handler->lock);
458}
459
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300460/**
461 * v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
462 * to the handler to initialize the hardware to the current control values.
463 * @hdl: The control handler.
464 *
465 * Button controls will be skipped, as are read-only controls.
466 *
467 * If @hdl == NULL, then this just returns 0.
468 */
Hans Verkuil09965172010-08-01 14:32:42 -0300469int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
470
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300471/**
472 * v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
473 * @hdl: The control handler.
474 * @prefix: The prefix to use when logging the control values. If the
475 * prefix does not end with a space, then ": " will be added
476 * after the prefix. If @prefix == NULL, then no prefix will be
477 * used.
478 *
479 * For use with VIDIOC_LOG_STATUS.
480 *
481 * Does nothing if @hdl == NULL.
482 */
Hans Verkuil09965172010-08-01 14:32:42 -0300483void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
484 const char *prefix);
485
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300486/**
487 * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300488 * control.
489 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300490 * @hdl: The control handler.
491 * @cfg: The control's configuration data.
492 * @priv: The control's driver-specific private data.
493 *
494 * If the &v4l2_ctrl struct could not be allocated then NULL is returned
495 * and @hdl->error is set to the error code (if it wasn't set already).
496 */
Hans Verkuil09965172010-08-01 14:32:42 -0300497struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300498 const struct v4l2_ctrl_config *cfg,
499 void *priv);
Hans Verkuil09965172010-08-01 14:32:42 -0300500
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300501/**
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300502 * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu
503 * control.
504 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300505 * @hdl: The control handler.
506 * @ops: The control ops.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300507 * @id: The control ID.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300508 * @min: The control's minimum value.
509 * @max: The control's maximum value.
510 * @step: The control's step value
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300511 * @def: The control's default value.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300512 *
513 * If the &v4l2_ctrl struct could not be allocated, or the control
514 * ID is not known, then NULL is returned and @hdl->error is set to the
515 * appropriate error code (if it wasn't set already).
516 *
517 * If @id refers to a menu control, then this function will return NULL.
518 *
519 * Use v4l2_ctrl_new_std_menu() when adding menu controls.
520 */
Hans Verkuil09965172010-08-01 14:32:42 -0300521struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300522 const struct v4l2_ctrl_ops *ops,
523 u32 id, s64 min, s64 max, u64 step,
524 s64 def);
Hans Verkuil09965172010-08-01 14:32:42 -0300525
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300526/**
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300527 * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2
528 * menu control.
529 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300530 * @hdl: The control handler.
531 * @ops: The control ops.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300532 * @id: The control ID.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300533 * @max: The control's maximum value.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300534 * @mask: The control's skip mask for menu controls. This makes it
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300535 * easy to skip menu items that are not valid. If bit X is set,
536 * then menu item X is skipped. Of course, this only works for
537 * menus with <= 64 menu items. There are no menus that come
538 * close to that number, so this is OK. Should we ever need more,
539 * then this will have to be extended to a bit array.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300540 * @def: The control's default value.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300541 *
542 * Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value
543 * determines which menu items are to be skipped.
544 *
545 * If @id refers to a non-menu control, then this function will return NULL.
546 */
Hans Verkuil09965172010-08-01 14:32:42 -0300547struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300548 const struct v4l2_ctrl_ops *ops,
549 u32 id, u8 max, u64 mask, u8 def);
Hans Verkuil09965172010-08-01 14:32:42 -0300550
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300551/**
552 * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300553 * with driver specific menu.
554 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300555 * @hdl: The control handler.
556 * @ops: The control ops.
557 * @id: The control ID.
558 * @max: The control's maximum value.
559 * @mask: The control's skip mask for menu controls. This makes it
560 * easy to skip menu items that are not valid. If bit X is set,
561 * then menu item X is skipped. Of course, this only works for
562 * menus with <= 64 menu items. There are no menus that come
563 * close to that number, so this is OK. Should we ever need more,
564 * then this will have to be extended to a bit array.
565 * @def: The control's default value.
566 * @qmenu: The new menu.
567 *
568 * Same as v4l2_ctrl_new_std_menu(), but @qmenu will be the driver specific
569 * menu of this control.
570 *
571 */
Lad, Prabhakar117a7112012-09-18 15:54:38 -0300572struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl,
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300573 const struct v4l2_ctrl_ops *ops,
574 u32 id, u8 max,
575 u64 mask, u8 def,
576 const char * const *qmenu);
Lad, Prabhakar117a7112012-09-18 15:54:38 -0300577
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300578/**
579 * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300580 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300581 * @hdl: The control handler.
582 * @ops: The control ops.
583 * @id: The control ID.
584 * @max: The control's maximum value.
585 * @def: The control's default value.
586 * @qmenu_int: The control's menu entries.
587 *
588 * Same as v4l2_ctrl_new_std_menu(), but @mask is set to 0 and it additionaly
589 * takes as an argument an array of integers determining the menu items.
590 *
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300591 * If @id refers to a non-integer-menu control, then this function will
592 * return %NULL.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300593 */
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300594struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300595 const struct v4l2_ctrl_ops *ops,
596 u32 id, u8 max, u8 def,
597 const s64 *qmenu_int);
Sylwester Nawrocki515f3282012-05-06 15:30:44 -0300598
Mauro Carvalho Chehab2257e182016-08-29 17:26:15 -0300599/**
600 * typedef v4l2_ctrl_filter - Typedef to define the filter function to be
601 * used when adding a control handler.
602 *
603 * @ctrl: pointer to struct &v4l2_ctrl.
604 */
605
Mauro Carvalho Chehab6d85d7d2016-07-22 10:58:03 -0300606typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl);
607
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300608/**
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300609 * v4l2_ctrl_add_handler() - Add all controls from handler @add to
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300610 * handler @hdl.
611 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300612 * @hdl: The control handler.
613 * @add: The control handler whose controls you want to add to
614 * the @hdl control handler.
615 * @filter: This function will filter which controls should be added.
616 *
617 * Does nothing if either of the two handlers is a NULL pointer.
618 * If @filter is NULL, then all controls are added. Otherwise only those
619 * controls for which @filter returns true will be added.
620 * In case of an error @hdl->error will be set to the error code (if it
621 * wasn't set already).
622 */
Hans Verkuil09965172010-08-01 14:32:42 -0300623int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
Hans Verkuil34a6b7d2012-09-14 07:15:03 -0300624 struct v4l2_ctrl_handler *add,
Mauro Carvalho Chehab6d85d7d2016-07-22 10:58:03 -0300625 v4l2_ctrl_filter filter);
Hans Verkuil09965172010-08-01 14:32:42 -0300626
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300627/**
628 * v4l2_ctrl_radio_filter() - Standard filter for radio controls.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300629 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300630 * @ctrl: The control that is filtered.
631 *
632 * This will return true for any controls that are valid for radio device
633 * nodes. Those are all of the V4L2_CID_AUDIO_* user controls and all FM
634 * transmitter class controls.
635 *
636 * This function is to be used with v4l2_ctrl_add_handler().
637 */
Hans Verkuil34a6b7d2012-09-14 07:15:03 -0300638bool v4l2_ctrl_radio_filter(const struct v4l2_ctrl *ctrl);
Hans Verkuil09965172010-08-01 14:32:42 -0300639
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300640/**
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300641 * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging
642 * to that cluster.
643 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300644 * @ncontrols: The number of controls in this cluster.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300645 * @controls: The cluster control array of size @ncontrols.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300646 */
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300647void v4l2_ctrl_cluster(unsigned int ncontrols, struct v4l2_ctrl **controls);
Hans Verkuil09965172010-08-01 14:32:42 -0300648
649
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300650/**
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300651 * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging
652 * to that cluster and set it up for autofoo/foo-type handling.
653 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300654 * @ncontrols: The number of controls in this cluster.
655 * @controls: The cluster control array of size @ncontrols. The first control
656 * must be the 'auto' control (e.g. autogain, autoexposure, etc.)
657 * @manual_val: The value for the first control in the cluster that equals the
658 * manual setting.
659 * @set_volatile: If true, then all controls except the first auto control will
660 * be volatile.
661 *
662 * Use for control groups where one control selects some automatic feature and
663 * the other controls are only active whenever the automatic feature is turned
664 * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
665 * red and blue balance, etc.
666 *
667 * The behavior of such controls is as follows:
668 *
669 * When the autofoo control is set to automatic, then any manual controls
670 * are set to inactive and any reads will call g_volatile_ctrl (if the control
671 * was marked volatile).
672 *
673 * When the autofoo control is set to manual, then any manual controls will
674 * be marked active, and any reads will just return the current value without
675 * going through g_volatile_ctrl.
676 *
Mauro Carvalho Chehab2257e182016-08-29 17:26:15 -0300677 * In addition, this function will set the %V4L2_CTRL_FLAG_UPDATE flag
678 * on the autofoo control and %V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300679 * if autofoo is in auto mode.
680 */
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300681void v4l2_ctrl_auto_cluster(unsigned int ncontrols,
682 struct v4l2_ctrl **controls,
683 u8 manual_val, bool set_volatile);
Hans Verkuil72d877c2011-06-10 05:44:36 -0300684
685
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300686/**
687 * v4l2_ctrl_find() - Find a control with the given ID.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300688 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300689 * @hdl: The control handler.
690 * @id: The control ID to find.
691 *
692 * If @hdl == NULL this will return NULL as well. Will lock the handler so
693 * do not use from inside &v4l2_ctrl_ops.
694 */
Hans Verkuil09965172010-08-01 14:32:42 -0300695struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id);
696
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300697/**
698 * v4l2_ctrl_activate() - Make the control active or inactive.
699 * @ctrl: The control to (de)activate.
700 * @active: True if the control should become active.
701 *
702 * This sets or clears the V4L2_CTRL_FLAG_INACTIVE flag atomically.
703 * Does nothing if @ctrl == NULL.
704 * This will usually be called from within the s_ctrl op.
705 * The V4L2_EVENT_CTRL event will be generated afterwards.
706 *
707 * This function assumes that the control handler is locked.
708 */
Hans Verkuil09965172010-08-01 14:32:42 -0300709void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
710
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300711/**
712 * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300713 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300714 * @ctrl: The control to (de)activate.
715 * @grabbed: True if the control should become grabbed.
716 *
717 * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically.
718 * Does nothing if @ctrl == NULL.
719 * The V4L2_EVENT_CTRL event will be generated afterwards.
720 * This will usually be called when starting or stopping streaming in the
721 * driver.
722 *
723 * This function assumes that the control handler is not locked and will
724 * take the lock itself.
725 */
Hans Verkuil09965172010-08-01 14:32:42 -0300726void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed);
727
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300728/**
729 *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
730 *
731 * @ctrl: The control to update.
732 * @min: The control's minimum value.
733 * @max: The control's maximum value.
734 * @step: The control's step value
735 * @def: The control's default value.
736 *
737 * Update the range of a control on the fly. This works for control types
738 * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
739 * @step value is interpreted as a menu_skip_mask.
740 *
741 * An error is returned if one of the range arguments is invalid for this
742 * control type.
743 *
744 * This function assumes that the control handler is not locked and will
745 * take the lock itself.
746 */
Sakari Ailus5a573922014-06-12 13:09:40 -0300747int __v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
748 s64 min, s64 max, u64 step, s64 def);
749
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300750/**
751 * v4l2_ctrl_modify_range() - Update the range of a control.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300752 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300753 * @ctrl: The control to update.
754 * @min: The control's minimum value.
755 * @max: The control's maximum value.
756 * @step: The control's step value
757 * @def: The control's default value.
758 *
759 * Update the range of a control on the fly. This works for control types
760 * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
761 * @step value is interpreted as a menu_skip_mask.
762 *
763 * An error is returned if one of the range arguments is invalid for this
764 * control type.
765 *
766 * This function assumes that the control handler is not locked and will
767 * take the lock itself.
768 */
Sakari Ailus5a573922014-06-12 13:09:40 -0300769static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
770 s64 min, s64 max, u64 step, s64 def)
771{
772 int rval;
773
774 v4l2_ctrl_lock(ctrl);
775 rval = __v4l2_ctrl_modify_range(ctrl, min, max, step, def);
776 v4l2_ctrl_unlock(ctrl);
777
778 return rval;
779}
Sylwester Nawrocki2ccbe772013-01-19 15:51:55 -0300780
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300781/**
782 * v4l2_ctrl_notify() - Function to set a notify callback for a control.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300783 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300784 * @ctrl: The control.
785 * @notify: The callback function.
786 * @priv: The callback private handle, passed as argument to the callback.
787 *
788 * This function sets a callback function for the control. If @ctrl is NULL,
789 * then it will do nothing. If @notify is NULL, then the notify callback will
790 * be removed.
791 *
792 * There can be only one notify. If another already exists, then a WARN_ON
793 * will be issued and the function will do nothing.
794 */
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300795void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify,
796 void *priv);
Hans Verkuil8ac7a942012-09-07 04:46:39 -0300797
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300798/**
799 * v4l2_ctrl_get_name() - Get the name of the control
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300800 *
Hans Verkuil79fbc202014-11-23 09:39:54 -0300801 * @id: The control ID.
802 *
803 * This function returns the name of the given control ID or NULL if it isn't
804 * a known control.
805 */
806const char *v4l2_ctrl_get_name(u32 id);
807
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300808/**
809 * v4l2_ctrl_get_menu() - Get the menu string array of the control
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300810 *
Hans Verkuil79fbc202014-11-23 09:39:54 -0300811 * @id: The control ID.
812 *
813 * This function returns the NULL-terminated menu string array name of the
814 * given control ID or NULL if it isn't a known menu control.
815 */
816const char * const *v4l2_ctrl_get_menu(u32 id);
817
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300818/**
819 * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300820 *
Hans Verkuil79fbc202014-11-23 09:39:54 -0300821 * @id: The control ID.
822 * @len: The size of the integer array.
823 *
824 * This function returns the integer array of the given control ID or NULL if it
825 * if it isn't a known integer menu control.
826 */
827const s64 *v4l2_ctrl_get_int_menu(u32 id, u32 *len);
828
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300829/**
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300830 * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from
831 * within a driver.
832 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300833 * @ctrl: The control.
834 *
835 * This returns the control's value safely by going through the control
836 * framework. This function will lock the control's handler, so it cannot be
837 * used from within the &v4l2_ctrl_ops functions.
838 *
839 * This function is for integer type controls only.
840 */
Hans Verkuil09965172010-08-01 14:32:42 -0300841s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
842
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300843/**
844 * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300845 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300846 * @ctrl: The control.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300847 * @val: TheControls name new value.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300848 *
Hans Verkuil904aef02016-06-15 09:57:48 -0300849 * This sets the control's new value safely by going through the control
850 * framework. This function assumes the control's handler is already locked,
851 * allowing it to be used from within the &v4l2_ctrl_ops functions.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300852 *
853 * This function is for integer type controls only.
854 */
Sakari Ailus0c4348a2014-06-12 13:09:42 -0300855int __v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300856
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300857/**
858 * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from
859 * within a driver.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300860 * @ctrl: The control.
861 * @val: The new value.
862 *
Hans Verkuil904aef02016-06-15 09:57:48 -0300863 * This sets the control's new value safely by going through the control
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300864 * framework. This function will lock the control's handler, so it cannot be
865 * used from within the &v4l2_ctrl_ops functions.
866 *
867 * This function is for integer type controls only.
868 */
Sakari Ailus0c4348a2014-06-12 13:09:42 -0300869static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
870{
871 int rval;
872
873 v4l2_ctrl_lock(ctrl);
874 rval = __v4l2_ctrl_s_ctrl(ctrl, val);
875 v4l2_ctrl_unlock(ctrl);
876
877 return rval;
878}
Hans Verkuil09965172010-08-01 14:32:42 -0300879
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300880/**
881 * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
882 * from within a driver.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300883 *
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300884 * @ctrl: The control.
885 *
886 * This returns the control's value safely by going through the control
887 * framework. This function will lock the control's handler, so it cannot be
888 * used from within the &v4l2_ctrl_ops functions.
889 *
890 * This function is for 64-bit integer type controls only.
891 */
Laurent Pinchart03d52852012-07-23 09:15:21 -0300892s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl);
893
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300894/**
895 * __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64().
896 *
897 * @ctrl: The control.
898 * @val: The new value.
899 *
Hans Verkuil904aef02016-06-15 09:57:48 -0300900 * This sets the control's new value safely by going through the control
901 * framework. This function assumes the control's handler is already locked,
902 * allowing it to be used from within the &v4l2_ctrl_ops functions.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300903 *
904 * This function is for 64-bit integer type controls only.
905 */
Sakari Ailus0c4348a2014-06-12 13:09:42 -0300906int __v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val);
907
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300908/**
909 * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300910 * from within a driver.
911 *
912 * @ctrl: The control.
913 * @val: The new value.
914 *
Hans Verkuil904aef02016-06-15 09:57:48 -0300915 * This sets the control's new value safely by going through the control
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300916 * framework. This function will lock the control's handler, so it cannot be
917 * used from within the &v4l2_ctrl_ops functions.
918 *
919 * This function is for 64-bit integer type controls only.
920 */
Sakari Ailus0c4348a2014-06-12 13:09:42 -0300921static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)
922{
923 int rval;
924
925 v4l2_ctrl_lock(ctrl);
926 rval = __v4l2_ctrl_s_ctrl_int64(ctrl, val);
927 v4l2_ctrl_unlock(ctrl);
928
929 return rval;
930}
Laurent Pinchart03d52852012-07-23 09:15:21 -0300931
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300932/**
933 * __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300934 *
935 * @ctrl: The control.
936 * @s: The new string.
937 *
Hans Verkuil904aef02016-06-15 09:57:48 -0300938 * This sets the control's new string safely by going through the control
939 * framework. This function assumes the control's handler is already locked,
940 * allowing it to be used from within the &v4l2_ctrl_ops functions.
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300941 *
942 * This function is for string type controls only.
943 */
Hans Verkuil5d0360a2014-07-21 10:45:42 -0300944int __v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s);
945
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300946/**
947 * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300948 * from within a driver.
949 *
950 * @ctrl: The control.
951 * @s: The new string.
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300952 *Controls name
Hans Verkuil904aef02016-06-15 09:57:48 -0300953 * This sets the control's new string safely by going through the control
Mauro Carvalho Chehab8c2721d2015-08-22 08:03:49 -0300954 * framework. This function will lock the control's handler, so it cannot be
955 * used from within the &v4l2_ctrl_ops functions.
956 *
957 * This function is for string type controls only.
958 */
Hans Verkuil5d0360a2014-07-21 10:45:42 -0300959static inline int v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s)
960{
961 int rval;
962
963 v4l2_ctrl_lock(ctrl);
964 rval = __v4l2_ctrl_s_ctrl_string(ctrl, s);
965 v4l2_ctrl_unlock(ctrl);
966
967 return rval;
968}
969
Hans Verkuilce727572011-06-10 05:56:39 -0300970/* Internal helper functions that deal with control events. */
Hans de Goede3e3661492012-04-08 12:59:47 -0300971extern const struct v4l2_subscribed_event_ops v4l2_ctrl_sub_ev_ops;
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300972
973/**
974 * v4l2_ctrl_replace - Function to be used as a callback to
975 * &struct v4l2_subscribed_event_ops replace\(\)
976 *
Mauro Carvalho Chehabf8441a42016-08-29 19:29:58 -0300977 * @old: pointer to struct &v4l2_event with the reported
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300978 * event;
Mauro Carvalho Chehabf8441a42016-08-29 19:29:58 -0300979 * @new: pointer to struct &v4l2_event with the modified
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300980 * event;
981 */
Hans de Goede3e3661492012-04-08 12:59:47 -0300982void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new);
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300983
984/**
985 * v4l2_ctrl_merge - Function to be used as a callback to
986 * &struct v4l2_subscribed_event_ops merge(\)
987 *
Mauro Carvalho Chehabf8441a42016-08-29 19:29:58 -0300988 * @old: pointer to struct &v4l2_event with the reported
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300989 * event;
Mauro Carvalho Chehabf8441a42016-08-29 19:29:58 -0300990 * @new: pointer to struct &v4l2_event with the merged
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300991 * event;
992 */
Hans de Goede3e3661492012-04-08 12:59:47 -0300993void v4l2_ctrl_merge(const struct v4l2_event *old, struct v4l2_event *new);
Hans Verkuil6e239392011-06-07 11:13:44 -0300994
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -0300995/**
996 * v4l2_ctrl_log_status - helper function to implement %VIDIOC_LOG_STATUS ioctl
997 *
998 * @file: pointer to struct file
999 * @fh: unused. Kept just to be compatible to the arguments expected by
1000 * &struct v4l2_ioctl_ops.vidioc_log_status.
1001 *
1002 * Can be used as a vidioc_log_status function that just dumps all controls
1003 * associated with the filehandle.
1004 */
Hans Verkuile2ecb252012-02-02 08:20:53 -03001005int v4l2_ctrl_log_status(struct file *file, void *fh);
1006
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -03001007/**
1008 * v4l2_ctrl_subscribe_event - Subscribes to an event
1009 *
1010 *
1011 * @fh: pointer to struct v4l2_fh
1012 * @sub: pointer to &struct v4l2_event_subscription
1013 *
1014 * Can be used as a vidioc_subscribe_event function that just subscribes
1015 * control events.
1016 */
Hans Verkuila26243b2012-01-27 16:18:42 -03001017int v4l2_ctrl_subscribe_event(struct v4l2_fh *fh,
Hans Verkuil85f5fe32012-09-04 11:46:09 -03001018 const struct v4l2_event_subscription *sub);
Hans Verkuila26243b2012-01-27 16:18:42 -03001019
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -03001020/**
1021 * v4l2_ctrl_poll - function to be used as a callback to the poll()
1022 * That just polls for control events.
1023 *
1024 * @file: pointer to struct file
1025 * @wait: pointer to struct poll_table_struct
1026 */
Hans Verkuila26243b2012-01-27 16:18:42 -03001027unsigned int v4l2_ctrl_poll(struct file *file, struct poll_table_struct *wait);
1028
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -03001029/* Helpers for ioctl_ops */
Hans Verkuil09965172010-08-01 14:32:42 -03001030
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -03001031/**
1032 * v4l2_queryctrl - Helper function to implement
1033 * :ref:`VIDIOC_QUERYCTRL <vidioc_queryctrl>` ioctl
1034 *
1035 * @hdl: pointer to &struct v4l2_ctrl_handler
1036 * @qc: pointer to &struct v4l2_queryctrl
1037 *
1038 * If hdl == NULL then they will all return -EINVAL.
1039 */
1040int v4l2_queryctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_queryctrl *qc);
1041
1042/**
1043 * v4l2_query_ext_ctrl - Helper function to implement
1044 * :ref:`VIDIOC_QUERY_EXT_CTRL <vidioc_queryctrl>` ioctl
1045 *
1046 * @hdl: pointer to &struct v4l2_ctrl_handler
1047 * @qc: pointer to &struct v4l2_query_ext_ctrl
1048 *
1049 * If hdl == NULL then they will all return -EINVAL.
1050 */
1051int v4l2_query_ext_ctrl(struct v4l2_ctrl_handler *hdl,
1052 struct v4l2_query_ext_ctrl *qc);
1053
1054/**
1055 * v4l2_querymenu - Helper function to implement
1056 * :ref:`VIDIOC_QUERYMENU <vidioc_queryctrl>` ioctl
1057 *
1058 * @hdl: pointer to &struct v4l2_ctrl_handler
1059 * @qm: pointer to &struct v4l2_querymenu
1060 *
1061 * If hdl == NULL then they will all return -EINVAL.
1062 */
1063int v4l2_querymenu(struct v4l2_ctrl_handler *hdl, struct v4l2_querymenu *qm);
1064
1065/**
1066 * v4l2_g_ctrl - Helper function to implement
1067 * :ref:`VIDIOC_G_CTRL <vidioc_g_ctrl>` ioctl
1068 *
1069 * @hdl: pointer to &struct v4l2_ctrl_handler
1070 * @ctrl: pointer to &struct v4l2_control
1071 *
1072 * If hdl == NULL then they will all return -EINVAL.
1073 */
1074int v4l2_g_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *ctrl);
1075
1076/**
1077 * v4l2_s_ctrl - Helper function to implement
1078 * :ref:`VIDIOC_S_CTRL <vidioc_g_ctrl>` ioctl
1079 *
1080 * @fh: pointer to &struct v4l2_fh
1081 * @hdl: pointer to &struct v4l2_ctrl_handler
1082 *
1083 * @ctrl: pointer to &struct v4l2_control
1084 *
1085 * If hdl == NULL then they will all return -EINVAL.
1086 */
1087int v4l2_s_ctrl(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
1088 struct v4l2_control *ctrl);
1089
1090/**
1091 * v4l2_g_ext_ctrls - Helper function to implement
1092 * :ref:`VIDIOC_G_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1093 *
1094 * @hdl: pointer to &struct v4l2_ctrl_handler
1095 * @c: pointer to &struct v4l2_ext_controls
1096 *
1097 * If hdl == NULL then they will all return -EINVAL.
1098 */
1099int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl,
1100 struct v4l2_ext_controls *c);
1101
1102/**
1103 * v4l2_try_ext_ctrls - Helper function to implement
1104 * :ref:`VIDIOC_TRY_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1105 *
1106 * @hdl: pointer to &struct v4l2_ctrl_handler
1107 * @c: pointer to &struct v4l2_ext_controls
1108 *
1109 * If hdl == NULL then they will all return -EINVAL.
1110 */
1111int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl,
1112 struct v4l2_ext_controls *c);
1113
1114/**
1115 * v4l2_s_ext_ctrls - Helper function to implement
1116 * :ref:`VIDIOC_S_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
1117 *
1118 * @fh: pointer to &struct v4l2_fh
1119 * @hdl: pointer to &struct v4l2_ctrl_handler
1120 * @c: pointer to &struct v4l2_ext_controls
1121 *
1122 * If hdl == NULL then they will all return -EINVAL.
1123 */
1124int v4l2_s_ext_ctrls(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
1125 struct v4l2_ext_controls *c);
1126
1127/**
1128 * v4l2_ctrl_subdev_subscribe_event - Helper function to implement
1129 * as a &struct v4l2_subdev_core_ops subscribe_event function
1130 * that just subscribes control events.
1131 *
1132 * @sd: pointer to &struct v4l2_subdev
1133 * @fh: pointer to &struct v4l2_fh
1134 * @sub: pointer to &struct v4l2_event_subscription
1135 */
Sylwester Nawrocki22fa4272013-01-22 19:00:23 -03001136int v4l2_ctrl_subdev_subscribe_event(struct v4l2_subdev *sd, struct v4l2_fh *fh,
1137 struct v4l2_event_subscription *sub);
1138
Mauro Carvalho Chehab8ec4bee2016-07-22 13:57:29 -03001139/**
1140 * v4l2_ctrl_subdev_log_status - Log all controls owned by subdev's control
1141 * handler.
1142 *
1143 * @sd: pointer to &struct v4l2_subdev
1144 */
Sylwester Nawrockiffa9b9f2013-01-22 19:01:02 -03001145int v4l2_ctrl_subdev_log_status(struct v4l2_subdev *sd);
1146
Hans Verkuil09965172010-08-01 14:32:42 -03001147#endif