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