v4l2-device.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538
  1. /*
  2. V4L2 device support header.
  3. Copyright (C) 2008 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_DEVICE_H
  17. #define _V4L2_DEVICE_H
  18. #include <media/media-device.h>
  19. #include <media/v4l2-subdev.h>
  20. #include <media/v4l2-dev.h>
  21. #define V4L2_DEVICE_NAME_SIZE (20 + 16)
  22. struct v4l2_ctrl_handler;
  23. /**
  24. * struct v4l2_device - main struct to for V4L2 device drivers
  25. *
  26. * @dev: pointer to struct device.
  27. * @mdev: pointer to struct media_device, may be NULL.
  28. * @subdevs: used to keep track of the registered subdevs
  29. * @lock: lock this struct; can be used by the driver as well
  30. * if this struct is embedded into a larger struct.
  31. * @name: unique device name, by default the driver name + bus ID
  32. * @notify: notify operation called by some sub-devices.
  33. * @ctrl_handler: The control handler. May be %NULL.
  34. * @prio: Device's priority state
  35. * @ref: Keep track of the references to this struct.
  36. * @release: Release function that is called when the ref count
  37. * goes to 0.
  38. *
  39. * Each instance of a V4L2 device should create the v4l2_device struct,
  40. * either stand-alone or embedded in a larger struct.
  41. *
  42. * It allows easy access to sub-devices (see v4l2-subdev.h) and provides
  43. * basic V4L2 device-level support.
  44. *
  45. * .. note::
  46. *
  47. * #) @dev->driver_data points to this struct.
  48. * #) @dev might be %NULL if there is no parent device
  49. */
  50. struct v4l2_device {
  51. struct device *dev;
  52. struct media_device *mdev;
  53. struct list_head subdevs;
  54. spinlock_t lock;
  55. char name[V4L2_DEVICE_NAME_SIZE];
  56. void (*notify)(struct v4l2_subdev *sd,
  57. unsigned int notification, void *arg);
  58. struct v4l2_ctrl_handler *ctrl_handler;
  59. struct v4l2_prio_state prio;
  60. struct kref ref;
  61. void (*release)(struct v4l2_device *v4l2_dev);
  62. };
  63. /**
  64. * v4l2_device_get - gets a V4L2 device reference
  65. *
  66. * @v4l2_dev: pointer to struct &v4l2_device
  67. *
  68. * This is an ancillary routine meant to increment the usage for the
  69. * struct &v4l2_device pointed by @v4l2_dev.
  70. */
  71. static inline void v4l2_device_get(struct v4l2_device *v4l2_dev)
  72. {
  73. kref_get(&v4l2_dev->ref);
  74. }
  75. /**
  76. * v4l2_device_put - putss a V4L2 device reference
  77. *
  78. * @v4l2_dev: pointer to struct &v4l2_device
  79. *
  80. * This is an ancillary routine meant to decrement the usage for the
  81. * struct &v4l2_device pointed by @v4l2_dev.
  82. */
  83. int v4l2_device_put(struct v4l2_device *v4l2_dev);
  84. /**
  85. * v4l2_device_register - Initialize v4l2_dev and make @dev->driver_data
  86. * point to @v4l2_dev.
  87. *
  88. * @dev: pointer to struct &device
  89. * @v4l2_dev: pointer to struct &v4l2_device
  90. *
  91. * .. note::
  92. * @dev may be %NULL in rare cases (ISA devices).
  93. * In such case the caller must fill in the @v4l2_dev->name field
  94. * before calling this function.
  95. */
  96. int __must_check v4l2_device_register(struct device *dev,
  97. struct v4l2_device *v4l2_dev);
  98. /**
  99. * v4l2_device_set_name - Optional function to initialize the
  100. * name field of struct &v4l2_device
  101. *
  102. * @v4l2_dev: pointer to struct &v4l2_device
  103. * @basename: base name for the device name
  104. * @instance: pointer to a static atomic_t var with the instance usage for
  105. * the device driver.
  106. *
  107. * v4l2_device_set_name() initializes the name field of struct &v4l2_device
  108. * using the driver name and a driver-global atomic_t instance.
  109. *
  110. * This function will increment the instance counter and returns the
  111. * instance value used in the name.
  112. *
  113. * Example:
  114. *
  115. * static atomic_t drv_instance = ATOMIC_INIT(0);
  116. *
  117. * ...
  118. *
  119. * instance = v4l2_device_set_name(&\ v4l2_dev, "foo", &\ drv_instance);
  120. *
  121. * The first time this is called the name field will be set to foo0 and
  122. * this function returns 0. If the name ends with a digit (e.g. cx18),
  123. * then the name will be set to cx18-0 since cx180 would look really odd.
  124. */
  125. int v4l2_device_set_name(struct v4l2_device *v4l2_dev, const char *basename,
  126. atomic_t *instance);
  127. /**
  128. * v4l2_device_disconnect - Change V4L2 device state to disconnected.
  129. *
  130. * @v4l2_dev: pointer to struct v4l2_device
  131. *
  132. * Should be called when the USB parent disconnects.
  133. * Since the parent disappears, this ensures that @v4l2_dev doesn't have
  134. * an invalid parent pointer.
  135. *
  136. * .. note:: This function sets @v4l2_dev->dev to NULL.
  137. */
  138. void v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
  139. /**
  140. * v4l2_device_unregister - Unregister all sub-devices and any other
  141. * resources related to @v4l2_dev.
  142. *
  143. * @v4l2_dev: pointer to struct v4l2_device
  144. */
  145. void v4l2_device_unregister(struct v4l2_device *v4l2_dev);
  146. /**
  147. * v4l2_device_register_subdev - Registers a subdev with a v4l2 device.
  148. *
  149. * @v4l2_dev: pointer to struct &v4l2_device
  150. * @sd: pointer to &struct v4l2_subdev
  151. *
  152. * While registered, the subdev module is marked as in-use.
  153. *
  154. * An error is returned if the module is no longer loaded on any attempts
  155. * to register it.
  156. */
  157. int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev,
  158. struct v4l2_subdev *sd);
  159. /**
  160. * v4l2_device_unregister_subdev - Unregisters a subdev with a v4l2 device.
  161. *
  162. * @sd: pointer to &struct v4l2_subdev
  163. *
  164. * .. note ::
  165. *
  166. * Can also be called if the subdev wasn't registered. In such
  167. * case, it will do nothing.
  168. */
  169. void v4l2_device_unregister_subdev(struct v4l2_subdev *sd);
  170. /**
  171. * v4l2_device_register_subdev_nodes - Registers device nodes for all subdevs
  172. * of the v4l2 device that are marked with
  173. * the %V4L2_SUBDEV_FL_HAS_DEVNODE flag.
  174. *
  175. * @v4l2_dev: pointer to struct v4l2_device
  176. */
  177. int __must_check
  178. v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev);
  179. /**
  180. * v4l2_subdev_notify - Sends a notification to v4l2_device.
  181. *
  182. * @sd: pointer to &struct v4l2_subdev
  183. * @notification: type of notification. Please notice that the notification
  184. * type is driver-specific.
  185. * @arg: arguments for the notification. Those are specific to each
  186. * notification type.
  187. */
  188. static inline void v4l2_subdev_notify(struct v4l2_subdev *sd,
  189. unsigned int notification, void *arg)
  190. {
  191. if (sd && sd->v4l2_dev && sd->v4l2_dev->notify)
  192. sd->v4l2_dev->notify(sd, notification, arg);
  193. }
  194. /**
  195. * v4l2_device_supports_requests - Test if requests are supported.
  196. *
  197. * @v4l2_dev: pointer to struct v4l2_device
  198. */
  199. static inline bool v4l2_device_supports_requests(struct v4l2_device *v4l2_dev)
  200. {
  201. return v4l2_dev->mdev && v4l2_dev->mdev->ops &&
  202. v4l2_dev->mdev->ops->req_queue;
  203. }
  204. /* Helper macros to iterate over all subdevs. */
  205. /**
  206. * v4l2_device_for_each_subdev - Helper macro that interates over all
  207. * sub-devices of a given &v4l2_device.
  208. *
  209. * @sd: pointer that will be filled by the macro with all
  210. * &struct v4l2_subdev pointer used as an iterator by the loop.
  211. * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
  212. *
  213. * This macro iterates over all sub-devices owned by the @v4l2_dev device.
  214. * It acts as a for loop iterator and executes the next statement with
  215. * the @sd variable pointing to each sub-device in turn.
  216. */
  217. #define v4l2_device_for_each_subdev(sd, v4l2_dev) \
  218. list_for_each_entry(sd, &(v4l2_dev)->subdevs, list)
  219. /**
  220. * __v4l2_device_call_subdevs_p - Calls the specified operation for
  221. * all subdevs matching the condition.
  222. *
  223. * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
  224. * @sd: pointer that will be filled by the macro with all
  225. * &struct v4l2_subdev pointer used as an iterator by the loop.
  226. * @cond: condition to be match
  227. * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
  228. * Each element there groups a set of operations functions.
  229. * @f: operation function that will be called if @cond matches.
  230. * The operation functions are defined in groups, according to
  231. * each element at &struct v4l2_subdev_ops.
  232. * @args...: arguments for @f.
  233. *
  234. * Ignore any errors.
  235. *
  236. * Note: subdevs cannot be added or deleted while walking
  237. * the subdevs list.
  238. */
  239. #define __v4l2_device_call_subdevs_p(v4l2_dev, sd, cond, o, f, args...) \
  240. do { \
  241. list_for_each_entry((sd), &(v4l2_dev)->subdevs, list) \
  242. if ((cond) && (sd)->ops->o && (sd)->ops->o->f) \
  243. (sd)->ops->o->f((sd) , ##args); \
  244. } while (0)
  245. /**
  246. * __v4l2_device_call_subdevs - Calls the specified operation for
  247. * all subdevs matching the condition.
  248. *
  249. * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
  250. * @cond: condition to be match
  251. * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
  252. * Each element there groups a set of operations functions.
  253. * @f: operation function that will be called if @cond matches.
  254. * The operation functions are defined in groups, according to
  255. * each element at &struct v4l2_subdev_ops.
  256. * @args...: arguments for @f.
  257. *
  258. * Ignore any errors.
  259. *
  260. * Note: subdevs cannot be added or deleted while walking
  261. * the subdevs list.
  262. */
  263. #define __v4l2_device_call_subdevs(v4l2_dev, cond, o, f, args...) \
  264. do { \
  265. struct v4l2_subdev *__sd; \
  266. \
  267. __v4l2_device_call_subdevs_p(v4l2_dev, __sd, cond, o, \
  268. f , ##args); \
  269. } while (0)
  270. /**
  271. * __v4l2_device_call_subdevs_until_err_p - Calls the specified operation for
  272. * all subdevs matching the condition.
  273. *
  274. * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
  275. * @sd: pointer that will be filled by the macro with all
  276. * &struct v4l2_subdev sub-devices associated with @v4l2_dev.
  277. * @cond: condition to be match
  278. * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
  279. * Each element there groups a set of operations functions.
  280. * @f: operation function that will be called if @cond matches.
  281. * The operation functions are defined in groups, according to
  282. * each element at &struct v4l2_subdev_ops.
  283. * @args...: arguments for @f.
  284. *
  285. * Return:
  286. *
  287. * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
  288. * for any subdevice, then abort and return with that error code, zero
  289. * otherwise.
  290. *
  291. * Note: subdevs cannot be added or deleted while walking
  292. * the subdevs list.
  293. */
  294. #define __v4l2_device_call_subdevs_until_err_p(v4l2_dev, sd, cond, o, f, args...) \
  295. ({ \
  296. long __err = 0; \
  297. \
  298. list_for_each_entry((sd), &(v4l2_dev)->subdevs, list) { \
  299. if ((cond) && (sd)->ops->o && (sd)->ops->o->f) \
  300. __err = (sd)->ops->o->f((sd) , ##args); \
  301. if (__err && __err != -ENOIOCTLCMD) \
  302. break; \
  303. } \
  304. (__err == -ENOIOCTLCMD) ? 0 : __err; \
  305. })
  306. /**
  307. * __v4l2_device_call_subdevs_until_err - Calls the specified operation for
  308. * all subdevs matching the condition.
  309. *
  310. * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
  311. * @cond: condition to be match
  312. * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
  313. * Each element there groups a set of operations functions.
  314. * @f: operation function that will be called if @cond matches.
  315. * The operation functions are defined in groups, according to
  316. * each element at &struct v4l2_subdev_ops.
  317. * @args...: arguments for @f.
  318. *
  319. * Return:
  320. *
  321. * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
  322. * for any subdevice, then abort and return with that error code,
  323. * zero otherwise.
  324. *
  325. * Note: subdevs cannot be added or deleted while walking
  326. * the subdevs list.
  327. */
  328. #define __v4l2_device_call_subdevs_until_err(v4l2_dev, cond, o, f, args...) \
  329. ({ \
  330. struct v4l2_subdev *__sd; \
  331. __v4l2_device_call_subdevs_until_err_p(v4l2_dev, __sd, cond, o, \
  332. f , ##args); \
  333. })
  334. /**
  335. * v4l2_device_call_all - Calls the specified operation for
  336. * all subdevs matching the &v4l2_subdev.grp_id, as assigned
  337. * by the bridge driver.
  338. *
  339. * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
  340. * @grpid: &struct v4l2_subdev->grp_id group ID to match.
  341. * Use 0 to match them all.
  342. * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
  343. * Each element there groups a set of operations functions.
  344. * @f: operation function that will be called if @cond matches.
  345. * The operation functions are defined in groups, according to
  346. * each element at &struct v4l2_subdev_ops.
  347. * @args...: arguments for @f.
  348. *
  349. * Ignore any errors.
  350. *
  351. * Note: subdevs cannot be added or deleted while walking
  352. * the subdevs list.
  353. */
  354. #define v4l2_device_call_all(v4l2_dev, grpid, o, f, args...) \
  355. do { \
  356. struct v4l2_subdev *__sd; \
  357. \
  358. __v4l2_device_call_subdevs_p(v4l2_dev, __sd, \
  359. !(grpid) || __sd->grp_id == (grpid), o, f , \
  360. ##args); \
  361. } while (0)
  362. /**
  363. * v4l2_device_call_until_err - Calls the specified operation for
  364. * all subdevs matching the &v4l2_subdev.grp_id, as assigned
  365. * by the bridge driver, until an error occurs.
  366. *
  367. * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
  368. * @grpid: &struct v4l2_subdev->grp_id group ID to match.
  369. * Use 0 to match them all.
  370. * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
  371. * Each element there groups a set of operations functions.
  372. * @f: operation function that will be called if @cond matches.
  373. * The operation functions are defined in groups, according to
  374. * each element at &struct v4l2_subdev_ops.
  375. * @args...: arguments for @f.
  376. *
  377. * Return:
  378. *
  379. * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
  380. * for any subdevice, then abort and return with that error code,
  381. * zero otherwise.
  382. *
  383. * Note: subdevs cannot be added or deleted while walking
  384. * the subdevs list.
  385. */
  386. #define v4l2_device_call_until_err(v4l2_dev, grpid, o, f, args...) \
  387. ({ \
  388. struct v4l2_subdev *__sd; \
  389. __v4l2_device_call_subdevs_until_err_p(v4l2_dev, __sd, \
  390. !(grpid) || __sd->grp_id == (grpid), o, f , \
  391. ##args); \
  392. })
  393. /**
  394. * v4l2_device_mask_call_all - Calls the specified operation for
  395. * all subdevices where a group ID matches a specified bitmask.
  396. *
  397. * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
  398. * @grpmsk: bitmask to be checked against &struct v4l2_subdev->grp_id
  399. * group ID to be matched. Use 0 to match them all.
  400. * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
  401. * Each element there groups a set of operations functions.
  402. * @f: operation function that will be called if @cond matches.
  403. * The operation functions are defined in groups, according to
  404. * each element at &struct v4l2_subdev_ops.
  405. * @args...: arguments for @f.
  406. *
  407. * Ignore any errors.
  408. *
  409. * Note: subdevs cannot be added or deleted while walking
  410. * the subdevs list.
  411. */
  412. #define v4l2_device_mask_call_all(v4l2_dev, grpmsk, o, f, args...) \
  413. do { \
  414. struct v4l2_subdev *__sd; \
  415. \
  416. __v4l2_device_call_subdevs_p(v4l2_dev, __sd, \
  417. !(grpmsk) || (__sd->grp_id & (grpmsk)), o, f , \
  418. ##args); \
  419. } while (0)
  420. /**
  421. * v4l2_device_mask_call_until_err - Calls the specified operation for
  422. * all subdevices where a group ID matches a specified bitmask.
  423. *
  424. * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
  425. * @grpmsk: bitmask to be checked against &struct v4l2_subdev->grp_id
  426. * group ID to be matched. Use 0 to match them all.
  427. * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
  428. * Each element there groups a set of operations functions.
  429. * @f: operation function that will be called if @cond matches.
  430. * The operation functions are defined in groups, according to
  431. * each element at &struct v4l2_subdev_ops.
  432. * @args...: arguments for @f.
  433. *
  434. * Return:
  435. *
  436. * If the operation returns an error other than 0 or ``-ENOIOCTLCMD``
  437. * for any subdevice, then abort and return with that error code,
  438. * zero otherwise.
  439. *
  440. * Note: subdevs cannot be added or deleted while walking
  441. * the subdevs list.
  442. */
  443. #define v4l2_device_mask_call_until_err(v4l2_dev, grpmsk, o, f, args...) \
  444. ({ \
  445. struct v4l2_subdev *__sd; \
  446. __v4l2_device_call_subdevs_until_err_p(v4l2_dev, __sd, \
  447. !(grpmsk) || (__sd->grp_id & (grpmsk)), o, f , \
  448. ##args); \
  449. })
  450. /**
  451. * v4l2_device_has_op - checks if any subdev with matching grpid has a
  452. * given ops.
  453. *
  454. * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
  455. * @grpid: &struct v4l2_subdev->grp_id group ID to match.
  456. * Use 0 to match them all.
  457. * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
  458. * Each element there groups a set of operations functions.
  459. * @f: operation function that will be called if @cond matches.
  460. * The operation functions are defined in groups, according to
  461. * each element at &struct v4l2_subdev_ops.
  462. */
  463. #define v4l2_device_has_op(v4l2_dev, grpid, o, f) \
  464. ({ \
  465. struct v4l2_subdev *__sd; \
  466. bool __result = false; \
  467. list_for_each_entry(__sd, &(v4l2_dev)->subdevs, list) { \
  468. if ((grpid) && __sd->grp_id != (grpid)) \
  469. continue; \
  470. if (v4l2_subdev_has_op(__sd, o, f)) { \
  471. __result = true; \
  472. break; \
  473. } \
  474. } \
  475. __result; \
  476. })
  477. /**
  478. * v4l2_device_mask_has_op - checks if any subdev with matching group
  479. * mask has a given ops.
  480. *
  481. * @v4l2_dev: &struct v4l2_device owning the sub-devices to iterate over.
  482. * @grpmsk: bitmask to be checked against &struct v4l2_subdev->grp_id
  483. * group ID to be matched. Use 0 to match them all.
  484. * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
  485. * Each element there groups a set of operations functions.
  486. * @f: operation function that will be called if @cond matches.
  487. * The operation functions are defined in groups, according to
  488. * each element at &struct v4l2_subdev_ops.
  489. */
  490. #define v4l2_device_mask_has_op(v4l2_dev, grpmsk, o, f) \
  491. ({ \
  492. struct v4l2_subdev *__sd; \
  493. bool __result = false; \
  494. list_for_each_entry(__sd, &(v4l2_dev)->subdevs, list) { \
  495. if ((grpmsk) && !(__sd->grp_id & (grpmsk))) \
  496. continue; \
  497. if (v4l2_subdev_has_op(__sd, o, f)) { \
  498. __result = true; \
  499. break; \
  500. } \
  501. } \
  502. __result; \
  503. })
  504. #endif