v4l2-ctrls.h 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688
  1. /*
  2. V4L2 controls support header.
  3. Copyright (C) 2010 Hans Verkuil <hverkuil@xs4all.nl>
  4. This program is free software; you can redistribute it and/or modify
  5. it under the terms of the GNU General Public License as published by
  6. the Free Software Foundation; either version 2 of the License, or
  7. (at your option) any later version.
  8. This program is distributed in the hope that it will be useful,
  9. but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11. GNU General Public License for more details.
  12. You should have received a copy of the GNU General Public License
  13. along with this program; if not, write to the Free Software
  14. Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  15. */
  16. #ifndef _V4L2_CTRLS_H
  17. #define _V4L2_CTRLS_H
  18. #include <linux/list.h>
  19. #include <linux/videodev2.h>
  20. /* forward references */
  21. struct file;
  22. struct v4l2_ctrl_handler;
  23. struct v4l2_ctrl_helper;
  24. struct v4l2_ctrl;
  25. struct video_device;
  26. struct v4l2_subdev;
  27. struct v4l2_subscribed_event;
  28. struct v4l2_fh;
  29. struct poll_table_struct;
  30. /** struct v4l2_ctrl_ops - The control operations that the driver has to provide.
  31. * @g_volatile_ctrl: Get a new value for this control. Generally only relevant
  32. * for volatile (and usually read-only) controls such as a control
  33. * that returns the current signal strength which changes
  34. * continuously.
  35. * If not set, then the currently cached value will be returned.
  36. * @try_ctrl: Test whether the control's value is valid. Only relevant when
  37. * the usual min/max/step checks are not sufficient.
  38. * @s_ctrl: Actually set the new control value. s_ctrl is compulsory. The
  39. * ctrl->handler->lock is held when these ops are called, so no
  40. * one else can access controls owned by that handler.
  41. */
  42. struct v4l2_ctrl_ops {
  43. int (*g_volatile_ctrl)(struct v4l2_ctrl *ctrl);
  44. int (*try_ctrl)(struct v4l2_ctrl *ctrl);
  45. int (*s_ctrl)(struct v4l2_ctrl *ctrl);
  46. };
  47. typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
  48. /** struct v4l2_ctrl - The control structure.
  49. * @node: The list node.
  50. * @ev_subs: The list of control event subscriptions.
  51. * @handler: The handler that owns the control.
  52. * @cluster: Point to start of cluster array.
  53. * @ncontrols: Number of controls in cluster array.
  54. * @done: Internal flag: set for each processed control.
  55. * @is_new: Set when the user specified a new value for this control. It
  56. * is also set when called from v4l2_ctrl_handler_setup. Drivers
  57. * should never set this flag.
  58. * @is_private: If set, then this control is private to its handler and it
  59. * will not be added to any other handlers. Drivers can set
  60. * this flag.
  61. * @is_auto: If set, then this control selects whether the other cluster
  62. * members are in 'automatic' mode or 'manual' mode. This is
  63. * used for autogain/gain type clusters. Drivers should never
  64. * set this flag directly.
  65. * @has_volatiles: If set, then one or more members of the cluster are volatile.
  66. * Drivers should never touch this flag.
  67. * @call_notify: If set, then call the handler's notify function whenever the
  68. * control's value changes.
  69. * @manual_mode_value: If the is_auto flag is set, then this is the value
  70. * of the auto control that determines if that control is in
  71. * manual mode. So if the value of the auto control equals this
  72. * value, then the whole cluster is in manual mode. Drivers should
  73. * never set this flag directly.
  74. * @ops: The control ops.
  75. * @id: The control ID.
  76. * @name: The control name.
  77. * @type: The control type.
  78. * @minimum: The control's minimum value.
  79. * @maximum: The control's maximum value.
  80. * @default_value: The control's default value.
  81. * @step: The control's step value for non-menu controls.
  82. * @menu_skip_mask: The control's skip mask for menu controls. This makes it
  83. * easy to skip menu items that are not valid. If bit X is set,
  84. * then menu item X is skipped. Of course, this only works for
  85. * menus with <= 32 menu items. There are no menus that come
  86. * close to that number, so this is OK. Should we ever need more,
  87. * then this will have to be extended to a u64 or a bit array.
  88. * @qmenu: A const char * array for all menu items. Array entries that are
  89. * empty strings ("") correspond to non-existing menu items (this
  90. * is in addition to the menu_skip_mask above). The last entry
  91. * must be NULL.
  92. * @flags: The control's flags.
  93. * @cur: The control's current value.
  94. * @val: The control's new s32 value.
  95. * @val64: The control's new s64 value.
  96. * @string: The control's new string value.
  97. * @priv: The control's private pointer. For use by the driver. It is
  98. * untouched by the control framework. Note that this pointer is
  99. * not freed when the control is deleted. Should this be needed
  100. * then a new internal bitfield can be added to tell the framework
  101. * to free this pointer.
  102. */
  103. struct v4l2_ctrl {
  104. /* Administrative fields */
  105. struct list_head node;
  106. struct list_head ev_subs;
  107. struct v4l2_ctrl_handler *handler;
  108. struct v4l2_ctrl **cluster;
  109. unsigned ncontrols;
  110. unsigned int done:1;
  111. unsigned int is_new:1;
  112. unsigned int is_private:1;
  113. unsigned int is_auto:1;
  114. unsigned int has_volatiles:1;
  115. unsigned int call_notify:1;
  116. unsigned int manual_mode_value:8;
  117. const struct v4l2_ctrl_ops *ops;
  118. u32 id;
  119. const char *name;
  120. enum v4l2_ctrl_type type;
  121. s32 minimum, maximum, default_value;
  122. union {
  123. u32 step;
  124. u32 menu_skip_mask;
  125. };
  126. union {
  127. const char * const *qmenu;
  128. const s64 *qmenu_int;
  129. };
  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. /** struct v4l2_ctrl_ref - The control reference.
  144. * @node: List node for the sorted list.
  145. * @next: Single-link list node for the hash.
  146. * @ctrl: The actual control information.
  147. * @helper: Pointer to helper struct. Used internally in prepare_ext_ctrls().
  148. *
  149. * Each control handler has a list of these refs. The list_head is used to
  150. * keep a sorted-by-control-ID list of all controls, while the next pointer
  151. * is used to link the control in the hash's bucket.
  152. */
  153. struct v4l2_ctrl_ref {
  154. struct list_head node;
  155. struct v4l2_ctrl_ref *next;
  156. struct v4l2_ctrl *ctrl;
  157. struct v4l2_ctrl_helper *helper;
  158. };
  159. /** struct v4l2_ctrl_handler - The control handler keeps track of all the
  160. * controls: both the controls owned by the handler and those inherited
  161. * from other handlers.
  162. * @_lock: Default for "lock".
  163. * @lock: Lock to control access to this handler and its controls.
  164. * May be replaced by the user right after init.
  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. * @notify: A notify callback that is called whenever the control changes value.
  172. * Note that the handler's lock is held when the notify function
  173. * is called!
  174. * @notify_priv: Passed as argument to the v4l2_ctrl notify callback.
  175. * @nr_of_buckets: Total number of buckets in the array.
  176. * @error: The error code of the first failed control addition.
  177. */
  178. struct v4l2_ctrl_handler {
  179. struct mutex _lock;
  180. struct mutex *lock;
  181. struct list_head ctrls;
  182. struct list_head ctrl_refs;
  183. struct v4l2_ctrl_ref *cached;
  184. struct v4l2_ctrl_ref **buckets;
  185. v4l2_ctrl_notify_fnc notify;
  186. void *notify_priv;
  187. u16 nr_of_buckets;
  188. int error;
  189. };
  190. /** struct v4l2_ctrl_config - Control configuration structure.
  191. * @ops: The control ops.
  192. * @id: The control ID.
  193. * @name: The control name.
  194. * @type: The control type.
  195. * @min: The control's minimum value.
  196. * @max: The control's maximum value.
  197. * @step: The control's step value for non-menu controls.
  198. * @def: The control's default value.
  199. * @flags: The control's flags.
  200. * @menu_skip_mask: The control's skip mask for menu controls. This makes it
  201. * easy to skip menu items that are not valid. If bit X is set,
  202. * then menu item X is skipped. Of course, this only works for
  203. * menus with <= 32 menu items. There are no menus that come
  204. * close to that number, so this is OK. Should we ever need more,
  205. * then this will have to be extended to a u64 or a bit array.
  206. * @qmenu: A const char * array for all menu items. Array entries that are
  207. * empty strings ("") correspond to non-existing menu items (this
  208. * is in addition to the menu_skip_mask above). The last entry
  209. * must be NULL.
  210. * @is_private: If set, then this control is private to its handler and it
  211. * will not be added to any other handlers.
  212. */
  213. struct v4l2_ctrl_config {
  214. const struct v4l2_ctrl_ops *ops;
  215. u32 id;
  216. const char *name;
  217. enum v4l2_ctrl_type type;
  218. s32 min;
  219. s32 max;
  220. u32 step;
  221. s32 def;
  222. u32 flags;
  223. u32 menu_skip_mask;
  224. const char * const *qmenu;
  225. const s64 *qmenu_int;
  226. unsigned int is_private:1;
  227. };
  228. /** v4l2_ctrl_fill() - Fill in the control fields based on the control ID.
  229. *
  230. * This works for all standard V4L2 controls.
  231. * For non-standard controls it will only fill in the given arguments
  232. * and @name will be NULL.
  233. *
  234. * This function will overwrite the contents of @name, @type and @flags.
  235. * The contents of @min, @max, @step and @def may be modified depending on
  236. * the type.
  237. *
  238. * Do not use in drivers! It is used internally for backwards compatibility
  239. * control handling only. Once all drivers are converted to use the new
  240. * control framework this function will no longer be exported.
  241. */
  242. void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
  243. s32 *min, s32 *max, s32 *step, s32 *def, u32 *flags);
  244. /** v4l2_ctrl_handler_init_class() - Initialize the control handler.
  245. * @hdl: The control handler.
  246. * @nr_of_controls_hint: A hint of how many controls this handler is
  247. * expected to refer to. This is the total number, so including
  248. * any inherited controls. It doesn't have to be precise, but if
  249. * it is way off, then you either waste memory (too many buckets
  250. * are allocated) or the control lookup becomes slower (not enough
  251. * buckets are allocated, so there are more slow list lookups).
  252. * It will always work, though.
  253. * @key: Used by the lock validator if CONFIG_LOCKDEP is set.
  254. * @name: Used by the lock validator if CONFIG_LOCKDEP is set.
  255. *
  256. * Returns an error if the buckets could not be allocated. This error will
  257. * also be stored in @hdl->error.
  258. *
  259. * Never use this call directly, always use the v4l2_ctrl_handler_init
  260. * macro that hides the @key and @name arguments.
  261. */
  262. int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
  263. unsigned nr_of_controls_hint,
  264. struct lock_class_key *key, const char *name);
  265. #ifdef CONFIG_LOCKDEP
  266. #define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint) \
  267. ( \
  268. ({ \
  269. static struct lock_class_key _key; \
  270. v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint, \
  271. &_key, \
  272. KBUILD_BASENAME ":" \
  273. __stringify(__LINE__) ":" \
  274. "(" #hdl ")->_lock"); \
  275. }) \
  276. )
  277. #else
  278. #define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint) \
  279. v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint, NULL, NULL)
  280. #endif
  281. /** v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
  282. * the control list.
  283. * @hdl: The control handler.
  284. *
  285. * Does nothing if @hdl == NULL.
  286. */
  287. void v4l2_ctrl_handler_free(struct v4l2_ctrl_handler *hdl);
  288. /** v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
  289. * to the handler to initialize the hardware to the current control values.
  290. * @hdl: The control handler.
  291. *
  292. * Button controls will be skipped, as are read-only controls.
  293. *
  294. * If @hdl == NULL, then this just returns 0.
  295. */
  296. int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
  297. /** v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
  298. * @hdl: The control handler.
  299. * @prefix: The prefix to use when logging the control values. If the
  300. * prefix does not end with a space, then ": " will be added
  301. * after the prefix. If @prefix == NULL, then no prefix will be
  302. * used.
  303. *
  304. * For use with VIDIOC_LOG_STATUS.
  305. *
  306. * Does nothing if @hdl == NULL.
  307. */
  308. void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
  309. const char *prefix);
  310. /** v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
  311. * control.
  312. * @hdl: The control handler.
  313. * @cfg: The control's configuration data.
  314. * @priv: The control's driver-specific private data.
  315. *
  316. * If the &v4l2_ctrl struct could not be allocated then NULL is returned
  317. * and @hdl->error is set to the error code (if it wasn't set already).
  318. */
  319. struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
  320. const struct v4l2_ctrl_config *cfg, void *priv);
  321. /** v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu control.
  322. * @hdl: The control handler.
  323. * @ops: The control ops.
  324. * @id: The control ID.
  325. * @min: The control's minimum value.
  326. * @max: The control's maximum value.
  327. * @step: The control's step value
  328. * @def: The control's default value.
  329. *
  330. * If the &v4l2_ctrl struct could not be allocated, or the control
  331. * ID is not known, then NULL is returned and @hdl->error is set to the
  332. * appropriate error code (if it wasn't set already).
  333. *
  334. * If @id refers to a menu control, then this function will return NULL.
  335. *
  336. * Use v4l2_ctrl_new_std_menu() when adding menu controls.
  337. */
  338. struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
  339. const struct v4l2_ctrl_ops *ops,
  340. u32 id, s32 min, s32 max, u32 step, s32 def);
  341. /** v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2 menu control.
  342. * @hdl: The control handler.
  343. * @ops: The control ops.
  344. * @id: The control ID.
  345. * @max: The control's maximum value.
  346. * @mask: The control's skip mask for menu controls. This makes it
  347. * easy to skip menu items that are not valid. If bit X is set,
  348. * then menu item X is skipped. Of course, this only works for
  349. * menus with <= 32 menu items. There are no menus that come
  350. * close to that number, so this is OK. Should we ever need more,
  351. * then this will have to be extended to a u64 or a bit array.
  352. * @def: The control's default value.
  353. *
  354. * Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value
  355. * determines which menu items are to be skipped.
  356. *
  357. * If @id refers to a non-menu control, then this function will return NULL.
  358. */
  359. struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
  360. const struct v4l2_ctrl_ops *ops,
  361. u32 id, s32 max, s32 mask, s32 def);
  362. /** v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
  363. * with driver specific menu.
  364. * @hdl: The control handler.
  365. * @ops: The control ops.
  366. * @id: The control ID.
  367. * @max: The control's maximum value.
  368. * @mask: The control's skip mask for menu controls. This makes it
  369. * easy to skip menu items that are not valid. If bit X is set,
  370. * then menu item X is skipped. Of course, this only works for
  371. * menus with <= 32 menu items. There are no menus that come
  372. * close to that number, so this is OK. Should we ever need more,
  373. * then this will have to be extended to a u64 or a bit array.
  374. * @def: The control's default value.
  375. * @qmenu: The new menu.
  376. *
  377. * Same as v4l2_ctrl_new_std_menu(), but @qmenu will be the driver specific
  378. * menu of this control.
  379. *
  380. */
  381. struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl,
  382. const struct v4l2_ctrl_ops *ops, u32 id, s32 max,
  383. s32 mask, s32 def, const char * const *qmenu);
  384. /** v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
  385. * @hdl: The control handler.
  386. * @ops: The control ops.
  387. * @id: The control ID.
  388. * @max: The control's maximum value.
  389. * @def: The control's default value.
  390. * @qmenu_int: The control's menu entries.
  391. *
  392. * Same as v4l2_ctrl_new_std_menu(), but @mask is set to 0 and it additionaly
  393. * takes as an argument an array of integers determining the menu items.
  394. *
  395. * If @id refers to a non-integer-menu control, then this function will return NULL.
  396. */
  397. struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
  398. const struct v4l2_ctrl_ops *ops,
  399. u32 id, s32 max, s32 def, const s64 *qmenu_int);
  400. /** v4l2_ctrl_add_ctrl() - Add a control from another handler to this handler.
  401. * @hdl: The control handler.
  402. * @ctrl: The control to add.
  403. *
  404. * It will return NULL if it was unable to add the control reference.
  405. * If the control already belonged to the handler, then it will do
  406. * nothing and just return @ctrl.
  407. */
  408. struct v4l2_ctrl *v4l2_ctrl_add_ctrl(struct v4l2_ctrl_handler *hdl,
  409. struct v4l2_ctrl *ctrl);
  410. /** v4l2_ctrl_add_handler() - Add all controls from handler @add to
  411. * handler @hdl.
  412. * @hdl: The control handler.
  413. * @add: The control handler whose controls you want to add to
  414. * the @hdl control handler.
  415. * @filter: This function will filter which controls should be added.
  416. *
  417. * Does nothing if either of the two handlers is a NULL pointer.
  418. * If @filter is NULL, then all controls are added. Otherwise only those
  419. * controls for which @filter returns true will be added.
  420. * In case of an error @hdl->error will be set to the error code (if it
  421. * wasn't set already).
  422. */
  423. int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
  424. struct v4l2_ctrl_handler *add,
  425. bool (*filter)(const struct v4l2_ctrl *ctrl));
  426. /** v4l2_ctrl_radio_filter() - Standard filter for radio controls.
  427. * @ctrl: The control that is filtered.
  428. *
  429. * This will return true for any controls that are valid for radio device
  430. * nodes. Those are all of the V4L2_CID_AUDIO_* user controls and all FM
  431. * transmitter class controls.
  432. *
  433. * This function is to be used with v4l2_ctrl_add_handler().
  434. */
  435. bool v4l2_ctrl_radio_filter(const struct v4l2_ctrl *ctrl);
  436. /** v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging to that cluster.
  437. * @ncontrols: The number of controls in this cluster.
  438. * @controls: The cluster control array of size @ncontrols.
  439. */
  440. void v4l2_ctrl_cluster(unsigned ncontrols, struct v4l2_ctrl **controls);
  441. /** v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging to
  442. * that cluster and set it up for autofoo/foo-type handling.
  443. * @ncontrols: The number of controls in this cluster.
  444. * @controls: The cluster control array of size @ncontrols. The first control
  445. * must be the 'auto' control (e.g. autogain, autoexposure, etc.)
  446. * @manual_val: The value for the first control in the cluster that equals the
  447. * manual setting.
  448. * @set_volatile: If true, then all controls except the first auto control will
  449. * be volatile.
  450. *
  451. * Use for control groups where one control selects some automatic feature and
  452. * the other controls are only active whenever the automatic feature is turned
  453. * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
  454. * red and blue balance, etc.
  455. *
  456. * The behavior of such controls is as follows:
  457. *
  458. * When the autofoo control is set to automatic, then any manual controls
  459. * are set to inactive and any reads will call g_volatile_ctrl (if the control
  460. * was marked volatile).
  461. *
  462. * When the autofoo control is set to manual, then any manual controls will
  463. * be marked active, and any reads will just return the current value without
  464. * going through g_volatile_ctrl.
  465. *
  466. * In addition, this function will set the V4L2_CTRL_FLAG_UPDATE flag
  467. * on the autofoo control and V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
  468. * if autofoo is in auto mode.
  469. */
  470. void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
  471. u8 manual_val, bool set_volatile);
  472. /** v4l2_ctrl_find() - Find a control with the given ID.
  473. * @hdl: The control handler.
  474. * @id: The control ID to find.
  475. *
  476. * If @hdl == NULL this will return NULL as well. Will lock the handler so
  477. * do not use from inside &v4l2_ctrl_ops.
  478. */
  479. struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id);
  480. /** v4l2_ctrl_activate() - Make the control active or inactive.
  481. * @ctrl: The control to (de)activate.
  482. * @active: True if the control should become active.
  483. *
  484. * This sets or clears the V4L2_CTRL_FLAG_INACTIVE flag atomically.
  485. * Does nothing if @ctrl == NULL.
  486. * This will usually be called from within the s_ctrl op.
  487. * The V4L2_EVENT_CTRL event will be generated afterwards.
  488. *
  489. * This function assumes that the control handler is locked.
  490. */
  491. void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
  492. /** v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
  493. * @ctrl: The control to (de)activate.
  494. * @grabbed: True if the control should become grabbed.
  495. *
  496. * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically.
  497. * Does nothing if @ctrl == NULL.
  498. * The V4L2_EVENT_CTRL event will be generated afterwards.
  499. * This will usually be called when starting or stopping streaming in the
  500. * driver.
  501. *
  502. * This function assumes that the control handler is not locked and will
  503. * take the lock itself.
  504. */
  505. void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed);
  506. /** v4l2_ctrl_modify_range() - Update the range of a control.
  507. * @ctrl: The control to update.
  508. * @min: The control's minimum value.
  509. * @max: The control's maximum value.
  510. * @step: The control's step value
  511. * @def: The control's default value.
  512. *
  513. * Update the range of a control on the fly. This works for control types
  514. * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
  515. * @step value is interpreted as a menu_skip_mask.
  516. *
  517. * An error is returned if one of the range arguments is invalid for this
  518. * control type.
  519. *
  520. * This function assumes that the control handler is not locked and will
  521. * take the lock itself.
  522. */
  523. int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
  524. s32 min, s32 max, u32 step, s32 def);
  525. /** v4l2_ctrl_lock() - Helper function to lock the handler
  526. * associated with the control.
  527. * @ctrl: The control to lock.
  528. */
  529. static inline void v4l2_ctrl_lock(struct v4l2_ctrl *ctrl)
  530. {
  531. mutex_lock(ctrl->handler->lock);
  532. }
  533. /** v4l2_ctrl_lock() - Helper function to unlock the handler
  534. * associated with the control.
  535. * @ctrl: The control to unlock.
  536. */
  537. static inline void v4l2_ctrl_unlock(struct v4l2_ctrl *ctrl)
  538. {
  539. mutex_unlock(ctrl->handler->lock);
  540. }
  541. /** v4l2_ctrl_notify() - Function to set a notify callback for a control.
  542. * @ctrl: The control.
  543. * @notify: The callback function.
  544. * @priv: The callback private handle, passed as argument to the callback.
  545. *
  546. * This function sets a callback function for the control. If @ctrl is NULL,
  547. * then it will do nothing. If @notify is NULL, then the notify callback will
  548. * be removed.
  549. *
  550. * There can be only one notify. If another already exists, then a WARN_ON
  551. * will be issued and the function will do nothing.
  552. */
  553. void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify, void *priv);
  554. /** v4l2_ctrl_g_ctrl() - Helper function to get the control's value from within a driver.
  555. * @ctrl: The control.
  556. *
  557. * This returns the control's value safely by going through the control
  558. * framework. This function will lock the control's handler, so it cannot be
  559. * used from within the &v4l2_ctrl_ops functions.
  560. *
  561. * This function is for integer type controls only.
  562. */
  563. s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
  564. /** v4l2_ctrl_s_ctrl() - Helper function to set the control's value from within a driver.
  565. * @ctrl: The control.
  566. * @val: The new value.
  567. *
  568. * This set the control's new value safely by going through the control
  569. * framework. This function will lock the control's handler, so it cannot be
  570. * used from within the &v4l2_ctrl_ops functions.
  571. *
  572. * This function is for integer type controls only.
  573. */
  574. int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
  575. /** v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value from within a driver.
  576. * @ctrl: The control.
  577. *
  578. * This returns the control's value safely by going through the control
  579. * framework. This function will lock the control's handler, so it cannot be
  580. * used from within the &v4l2_ctrl_ops functions.
  581. *
  582. * This function is for 64-bit integer type controls only.
  583. */
  584. s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl);
  585. /** v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value from within a driver.
  586. * @ctrl: The control.
  587. * @val: The new value.
  588. *
  589. * This set the control's new value safely by going through the control
  590. * framework. This function will lock the control's handler, so it cannot be
  591. * used from within the &v4l2_ctrl_ops functions.
  592. *
  593. * This function is for 64-bit integer type controls only.
  594. */
  595. int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val);
  596. /* Internal helper functions that deal with control events. */
  597. extern const struct v4l2_subscribed_event_ops v4l2_ctrl_sub_ev_ops;
  598. void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new);
  599. void v4l2_ctrl_merge(const struct v4l2_event *old, struct v4l2_event *new);
  600. /* Can be used as a vidioc_log_status function that just dumps all controls
  601. associated with the filehandle. */
  602. int v4l2_ctrl_log_status(struct file *file, void *fh);
  603. /* Can be used as a vidioc_subscribe_event function that just subscribes
  604. control events. */
  605. int v4l2_ctrl_subscribe_event(struct v4l2_fh *fh,
  606. const struct v4l2_event_subscription *sub);
  607. /* Can be used as a poll function that just polls for control events. */
  608. unsigned int v4l2_ctrl_poll(struct file *file, struct poll_table_struct *wait);
  609. /* Helpers for ioctl_ops. If hdl == NULL then they will all return -EINVAL. */
  610. int v4l2_queryctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_queryctrl *qc);
  611. int v4l2_querymenu(struct v4l2_ctrl_handler *hdl, struct v4l2_querymenu *qm);
  612. int v4l2_g_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *ctrl);
  613. int v4l2_s_ctrl(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
  614. struct v4l2_control *ctrl);
  615. int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *c);
  616. int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *c);
  617. int v4l2_s_ext_ctrls(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
  618. struct v4l2_ext_controls *c);
  619. /* Helpers for subdevices. If the associated ctrl_handler == NULL then they
  620. will all return -EINVAL. */
  621. int v4l2_subdev_queryctrl(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc);
  622. int v4l2_subdev_querymenu(struct v4l2_subdev *sd, struct v4l2_querymenu *qm);
  623. int v4l2_subdev_g_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs);
  624. int v4l2_subdev_try_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs);
  625. int v4l2_subdev_s_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs);
  626. int v4l2_subdev_g_ctrl(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
  627. int v4l2_subdev_s_ctrl(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
  628. /* Can be used as a subscribe_event function that just subscribes control
  629. events. */
  630. int v4l2_ctrl_subdev_subscribe_event(struct v4l2_subdev *sd, struct v4l2_fh *fh,
  631. struct v4l2_event_subscription *sub);
  632. /* Log all controls owned by subdev's control handler. */
  633. int v4l2_ctrl_subdev_log_status(struct v4l2_subdev *sd);
  634. #endif