[media] V4L: soc-camera: add a livecrop host operation
[linux-2.6.git] / include / media / v4l2-ctrls.h
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/device.h>
26 #include <linux/videodev2.h>
27
28 /* forward references */
29 struct v4l2_ctrl_handler;
30 struct v4l2_ctrl;
31 struct video_device;
32 struct v4l2_subdev;
33
34 /** struct v4l2_ctrl_ops - The control operations that the driver has to provide.
35   * @g_volatile_ctrl: Get a new value for this control. Generally only relevant
36   *             for volatile (and usually read-only) controls such as a control
37   *             that returns the current signal strength which changes
38   *             continuously.
39   *             If not set, then the currently cached value will be returned.
40   * @try_ctrl:  Test whether the control's value is valid. Only relevant when
41   *             the usual min/max/step checks are not sufficient.
42   * @s_ctrl:    Actually set the new control value. s_ctrl is compulsory. The
43   *             ctrl->handler->lock is held when these ops are called, so no
44   *             one else can access controls owned by that handler.
45   */
46 struct v4l2_ctrl_ops {
47         int (*g_volatile_ctrl)(struct v4l2_ctrl *ctrl);
48         int (*try_ctrl)(struct v4l2_ctrl *ctrl);
49         int (*s_ctrl)(struct v4l2_ctrl *ctrl);
50 };
51
52 /** struct v4l2_ctrl - The control structure.
53   * @node:      The list node.
54   * @handler:   The handler that owns the control.
55   * @cluster:   Point to start of cluster array.
56   * @ncontrols: Number of controls in cluster array.
57   * @done:      Internal flag: set for each processed control.
58   * @is_new:    Set when the user specified a new value for this control. It
59   *             is also set when called from v4l2_ctrl_handler_setup. Drivers
60   *             should never set this flag.
61   * @is_private: If set, then this control is private to its handler and it
62   *             will not be added to any other handlers. Drivers can set
63   *             this flag.
64   * @is_volatile: If set, then this control is volatile. This means that the
65   *             control's current value cannot be cached and needs to be
66   *             retrieved through the g_volatile_ctrl op. Drivers can set
67   *             this flag.
68   * @ops:       The control ops.
69   * @id:        The control ID.
70   * @name:      The control name.
71   * @type:      The control type.
72   * @minimum:   The control's minimum value.
73   * @maximum:   The control's maximum value.
74   * @default_value: The control's default value.
75   * @step:      The control's step value for non-menu controls.
76   * @menu_skip_mask: The control's skip mask for menu controls. This makes it
77   *             easy to skip menu items that are not valid. If bit X is set,
78   *             then menu item X is skipped. Of course, this only works for
79   *             menus with <= 32 menu items. There are no menus that come
80   *             close to that number, so this is OK. Should we ever need more,
81   *             then this will have to be extended to a u64 or a bit array.
82   * @qmenu:     A const char * array for all menu items. Array entries that are
83   *             empty strings ("") correspond to non-existing menu items (this
84   *             is in addition to the menu_skip_mask above). The last entry
85   *             must be NULL.
86   * @flags:     The control's flags.
87   * @cur:       The control's current value.
88   * @val:       The control's new s32 value.
89   * @val64:     The control's new s64 value.
90   * @string:    The control's new string value.
91   * @priv:      The control's private pointer. For use by the driver. It is
92   *             untouched by the control framework. Note that this pointer is
93   *             not freed when the control is deleted. Should this be needed
94   *             then a new internal bitfield can be added to tell the framework
95   *             to free this pointer.
96   */
97 struct v4l2_ctrl {
98         /* Administrative fields */
99         struct list_head node;
100         struct v4l2_ctrl_handler *handler;
101         struct v4l2_ctrl **cluster;
102         unsigned ncontrols;
103         unsigned int done:1;
104
105         unsigned int is_new:1;
106         unsigned int is_private:1;
107         unsigned int is_volatile:1;
108
109         const struct v4l2_ctrl_ops *ops;
110         u32 id;
111         const char *name;
112         enum v4l2_ctrl_type type;
113         s32 minimum, maximum, default_value;
114         union {
115                 u32 step;
116                 u32 menu_skip_mask;
117         };
118         const char * const *qmenu;
119         unsigned long flags;
120         union {
121                 s32 val;
122                 s64 val64;
123                 char *string;
124         } cur;
125         union {
126                 s32 val;
127                 s64 val64;
128                 char *string;
129         };
130         void *priv;
131 };
132
133 /** struct v4l2_ctrl_ref - The control reference.
134   * @node:      List node for the sorted list.
135   * @next:      Single-link list node for the hash.
136   * @ctrl:      The actual control information.
137   *
138   * Each control handler has a list of these refs. The list_head is used to
139   * keep a sorted-by-control-ID list of all controls, while the next pointer
140   * is used to link the control in the hash's bucket.
141   */
142 struct v4l2_ctrl_ref {
143         struct list_head node;
144         struct v4l2_ctrl_ref *next;
145         struct v4l2_ctrl *ctrl;
146 };
147
148 /** struct v4l2_ctrl_handler - The control handler keeps track of all the
149   * controls: both the controls owned by the handler and those inherited
150   * from other handlers.
151   * @lock:      Lock to control access to this handler and its controls.
152   * @ctrls:     The list of controls owned by this handler.
153   * @ctrl_refs: The list of control references.
154   * @cached:    The last found control reference. It is common that the same
155   *             control is needed multiple times, so this is a simple
156   *             optimization.
157   * @buckets:   Buckets for the hashing. Allows for quick control lookup.
158   * @nr_of_buckets: Total number of buckets in the array.
159   * @error:     The error code of the first failed control addition.
160   */
161 struct v4l2_ctrl_handler {
162         struct mutex lock;
163         struct list_head ctrls;
164         struct list_head ctrl_refs;
165         struct v4l2_ctrl_ref *cached;
166         struct v4l2_ctrl_ref **buckets;
167         u16 nr_of_buckets;
168         int error;
169 };
170
171 /** struct v4l2_ctrl_config - Control configuration structure.
172   * @ops:       The control ops.
173   * @id:        The control ID.
174   * @name:      The control name.
175   * @type:      The control type.
176   * @min:       The control's minimum value.
177   * @max:       The control's maximum value.
178   * @step:      The control's step value for non-menu controls.
179   * @def:       The control's default value.
180   * @flags:     The control's flags.
181   * @menu_skip_mask: The control's skip mask for menu controls. This makes it
182   *             easy to skip menu items that are not valid. If bit X is set,
183   *             then menu item X is skipped. Of course, this only works for
184   *             menus with <= 32 menu items. There are no menus that come
185   *             close to that number, so this is OK. Should we ever need more,
186   *             then this will have to be extended to a u64 or a bit array.
187   * @qmenu:     A const char * array for all menu items. Array entries that are
188   *             empty strings ("") correspond to non-existing menu items (this
189   *             is in addition to the menu_skip_mask above). The last entry
190   *             must be NULL.
191   * @is_private: If set, then this control is private to its handler and it
192   *             will not be added to any other handlers.
193   * @is_volatile: If set, then this control is volatile. This means that the
194   *             control's current value cannot be cached and needs to be
195   *             retrieved through the g_volatile_ctrl op.
196   */
197 struct v4l2_ctrl_config {
198         const struct v4l2_ctrl_ops *ops;
199         u32 id;
200         const char *name;
201         enum v4l2_ctrl_type type;
202         s32 min;
203         s32 max;
204         u32 step;
205         s32 def;
206         u32 flags;
207         u32 menu_skip_mask;
208         const char * const *qmenu;
209         unsigned int is_private:1;
210         unsigned int is_volatile:1;
211 };
212
213 /** v4l2_ctrl_fill() - Fill in the control fields based on the control ID.
214   *
215   * This works for all standard V4L2 controls.
216   * For non-standard controls it will only fill in the given arguments
217   * and @name will be NULL.
218   *
219   * This function will overwrite the contents of @name, @type and @flags.
220   * The contents of @min, @max, @step and @def may be modified depending on
221   * the type.
222   *
223   * Do not use in drivers! It is used internally for backwards compatibility
224   * control handling only. Once all drivers are converted to use the new
225   * control framework this function will no longer be exported.
226   */
227 void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
228                     s32 *min, s32 *max, s32 *step, s32 *def, u32 *flags);
229
230
231 /** v4l2_ctrl_handler_init() - Initialize the control handler.
232   * @hdl:       The control handler.
233   * @nr_of_controls_hint: A hint of how many controls this handler is
234   *             expected to refer to. This is the total number, so including
235   *             any inherited controls. It doesn't have to be precise, but if
236   *             it is way off, then you either waste memory (too many buckets
237   *             are allocated) or the control lookup becomes slower (not enough
238   *             buckets are allocated, so there are more slow list lookups).
239   *             It will always work, though.
240   *
241   * Returns an error if the buckets could not be allocated. This error will
242   * also be stored in @hdl->error.
243   */
244 int v4l2_ctrl_handler_init(struct v4l2_ctrl_handler *hdl,
245                            unsigned nr_of_controls_hint);
246
247 /** v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
248   * the control list.
249   * @hdl:       The control handler.
250   *
251   * Does nothing if @hdl == NULL.
252   */
253 void v4l2_ctrl_handler_free(struct v4l2_ctrl_handler *hdl);
254
255 /** v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
256   * to the handler to initialize the hardware to the current control values.
257   * @hdl:       The control handler.
258   *
259   * Button controls will be skipped, as are read-only controls.
260   *
261   * If @hdl == NULL, then this just returns 0.
262   */
263 int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
264
265 /** v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
266   * @hdl:       The control handler.
267   * @prefix:    The prefix to use when logging the control values. If the
268   *             prefix does not end with a space, then ": " will be added
269   *             after the prefix. If @prefix == NULL, then no prefix will be
270   *             used.
271   *
272   * For use with VIDIOC_LOG_STATUS.
273   *
274   * Does nothing if @hdl == NULL.
275   */
276 void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
277                                   const char *prefix);
278
279 /** v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
280   * control.
281   * @hdl:       The control handler.
282   * @cfg:       The control's configuration data.
283   * @priv:      The control's driver-specific private data.
284   *
285   * If the &v4l2_ctrl struct could not be allocated then NULL is returned
286   * and @hdl->error is set to the error code (if it wasn't set already).
287   */
288 struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
289                         const struct v4l2_ctrl_config *cfg, void *priv);
290
291 /** v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu control.
292   * @hdl:       The control handler.
293   * @ops:       The control ops.
294   * @id:        The control ID.
295   * @min:       The control's minimum value.
296   * @max:       The control's maximum value.
297   * @step:      The control's step value
298   * @def:       The control's default value.
299   *
300   * If the &v4l2_ctrl struct could not be allocated, or the control
301   * ID is not known, then NULL is returned and @hdl->error is set to the
302   * appropriate error code (if it wasn't set already).
303   *
304   * If @id refers to a menu control, then this function will return NULL.
305   *
306   * Use v4l2_ctrl_new_std_menu() when adding menu controls.
307   */
308 struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
309                         const struct v4l2_ctrl_ops *ops,
310                         u32 id, s32 min, s32 max, u32 step, s32 def);
311
312 /** v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2 menu control.
313   * @hdl:       The control handler.
314   * @ops:       The control ops.
315   * @id:        The control ID.
316   * @max:       The control's maximum value.
317   * @mask:      The control's skip mask for menu controls. This makes it
318   *             easy to skip menu items that are not valid. If bit X is set,
319   *             then menu item X is skipped. Of course, this only works for
320   *             menus with <= 32 menu items. There are no menus that come
321   *             close to that number, so this is OK. Should we ever need more,
322   *             then this will have to be extended to a u64 or a bit array.
323   * @def:       The control's default value.
324   *
325   * Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value
326   * determines which menu items are to be skipped.
327   *
328   * If @id refers to a non-menu control, then this function will return NULL.
329   */
330 struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
331                         const struct v4l2_ctrl_ops *ops,
332                         u32 id, s32 max, s32 mask, s32 def);
333
334 /** v4l2_ctrl_add_ctrl() - Add a control from another handler to this handler.
335   * @hdl:       The control handler.
336   * @ctrl:      The control to add.
337   *
338   * It will return NULL if it was unable to add the control reference.
339   * If the control already belonged to the handler, then it will do
340   * nothing and just return @ctrl.
341   */
342 struct v4l2_ctrl *v4l2_ctrl_add_ctrl(struct v4l2_ctrl_handler *hdl,
343                                           struct v4l2_ctrl *ctrl);
344
345 /** v4l2_ctrl_add_handler() - Add all controls from handler @add to
346   * handler @hdl.
347   * @hdl:       The control handler.
348   * @add:       The control handler whose controls you want to add to
349   *             the @hdl control handler.
350   *
351   * Does nothing if either of the two is a NULL pointer.
352   * In case of an error @hdl->error will be set to the error code (if it
353   * wasn't set already).
354   */
355 int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
356                           struct v4l2_ctrl_handler *add);
357
358
359 /** v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging to that cluster.
360   * @ncontrols: The number of controls in this cluster.
361   * @controls:  The cluster control array of size @ncontrols.
362   */
363 void v4l2_ctrl_cluster(unsigned ncontrols, struct v4l2_ctrl **controls);
364
365
366 /** v4l2_ctrl_find() - Find a control with the given ID.
367   * @hdl:       The control handler.
368   * @id:        The control ID to find.
369   *
370   * If @hdl == NULL this will return NULL as well. Will lock the handler so
371   * do not use from inside &v4l2_ctrl_ops.
372   */
373 struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id);
374
375 /** v4l2_ctrl_activate() - Make the control active or inactive.
376   * @ctrl:      The control to (de)activate.
377   * @active:    True if the control should become active.
378   *
379   * This sets or clears the V4L2_CTRL_FLAG_INACTIVE flag atomically.
380   * Does nothing if @ctrl == NULL.
381   * This will usually be called from within the s_ctrl op.
382   *
383   * This function can be called regardless of whether the control handler
384   * is locked or not.
385   */
386 void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
387
388 /** v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
389   * @ctrl:      The control to (de)activate.
390   * @grabbed:   True if the control should become grabbed.
391   *
392   * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically.
393   * Does nothing if @ctrl == NULL.
394   * This will usually be called when starting or stopping streaming in the
395   * driver.
396   *
397   * This function can be called regardless of whether the control handler
398   * is locked or not.
399   */
400 void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed);
401
402 /** v4l2_ctrl_lock() - Helper function to lock the handler
403   * associated with the control.
404   * @ctrl:      The control to lock.
405   */
406 static inline void v4l2_ctrl_lock(struct v4l2_ctrl *ctrl)
407 {
408         mutex_lock(&ctrl->handler->lock);
409 }
410
411 /** v4l2_ctrl_lock() - Helper function to unlock the handler
412   * associated with the control.
413   * @ctrl:      The control to unlock.
414   */
415 static inline void v4l2_ctrl_unlock(struct v4l2_ctrl *ctrl)
416 {
417         mutex_unlock(&ctrl->handler->lock);
418 }
419
420 /** v4l2_ctrl_g_ctrl() - Helper function to get the control's value from within a driver.
421   * @ctrl:      The control.
422   *
423   * This returns the control's value safely by going through the control
424   * framework. This function will lock the control's handler, so it cannot be
425   * used from within the &v4l2_ctrl_ops functions.
426   *
427   * This function is for integer type controls only.
428   */
429 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
430
431 /** v4l2_ctrl_s_ctrl() - Helper function to set the control's value from within a driver.
432   * @ctrl:      The control.
433   * @val:       The new value.
434   *
435   * This set the control's new value safely by going through the control
436   * framework. This function will lock the control's handler, so it cannot be
437   * used from within the &v4l2_ctrl_ops functions.
438   *
439   * This function is for integer type controls only.
440   */
441 int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
442
443
444 /* Helpers for ioctl_ops. If hdl == NULL then they will all return -EINVAL. */
445 int v4l2_queryctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_queryctrl *qc);
446 int v4l2_querymenu(struct v4l2_ctrl_handler *hdl, struct v4l2_querymenu *qm);
447 int v4l2_g_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *ctrl);
448 int v4l2_s_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *ctrl);
449 int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *c);
450 int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *c);
451 int v4l2_s_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *c);
452
453 /* Helpers for subdevices. If the associated ctrl_handler == NULL then they
454    will all return -EINVAL. */
455 int v4l2_subdev_queryctrl(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc);
456 int v4l2_subdev_querymenu(struct v4l2_subdev *sd, struct v4l2_querymenu *qm);
457 int v4l2_subdev_g_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs);
458 int v4l2_subdev_try_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs);
459 int v4l2_subdev_s_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs);
460 int v4l2_subdev_g_ctrl(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
461 int v4l2_subdev_s_ctrl(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
462
463 #endif