v4l2-event.h 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208
  1. /* SPDX-License-Identifier: GPL-2.0-only */
  2. /*
  3. * v4l2-event.h
  4. *
  5. * V4L2 events.
  6. *
  7. * Copyright (C) 2009--2010 Nokia Corporation.
  8. *
  9. * Contact: Sakari Ailus <[email protected]>
  10. */
  11. #ifndef V4L2_EVENT_H
  12. #define V4L2_EVENT_H
  13. #include <linux/types.h>
  14. #include <linux/videodev2.h>
  15. #include <linux/wait.h>
  16. struct v4l2_fh;
  17. struct v4l2_subdev;
  18. struct v4l2_subscribed_event;
  19. struct video_device;
  20. /**
  21. * struct v4l2_kevent - Internal kernel event struct.
  22. * @list: List node for the v4l2_fh->available list.
  23. * @sev: Pointer to parent v4l2_subscribed_event.
  24. * @event: The event itself.
  25. * @ts: The timestamp of the event.
  26. */
  27. struct v4l2_kevent {
  28. struct list_head list;
  29. struct v4l2_subscribed_event *sev;
  30. struct v4l2_event event;
  31. u64 ts;
  32. };
  33. /**
  34. * struct v4l2_subscribed_event_ops - Subscribed event operations.
  35. *
  36. * @add: Optional callback, called when a new listener is added
  37. * @del: Optional callback, called when a listener stops listening
  38. * @replace: Optional callback that can replace event 'old' with event 'new'.
  39. * @merge: Optional callback that can merge event 'old' into event 'new'.
  40. */
  41. struct v4l2_subscribed_event_ops {
  42. int (*add)(struct v4l2_subscribed_event *sev, unsigned int elems);
  43. void (*del)(struct v4l2_subscribed_event *sev);
  44. void (*replace)(struct v4l2_event *old, const struct v4l2_event *new);
  45. void (*merge)(const struct v4l2_event *old, struct v4l2_event *new);
  46. };
  47. /**
  48. * struct v4l2_subscribed_event - Internal struct representing a subscribed
  49. * event.
  50. *
  51. * @list: List node for the v4l2_fh->subscribed list.
  52. * @type: Event type.
  53. * @id: Associated object ID (e.g. control ID). 0 if there isn't any.
  54. * @flags: Copy of v4l2_event_subscription->flags.
  55. * @fh: Filehandle that subscribed to this event.
  56. * @node: List node that hooks into the object's event list
  57. * (if there is one).
  58. * @ops: v4l2_subscribed_event_ops
  59. * @elems: The number of elements in the events array.
  60. * @first: The index of the events containing the oldest available event.
  61. * @in_use: The number of queued events.
  62. * @events: An array of @elems events.
  63. */
  64. struct v4l2_subscribed_event {
  65. struct list_head list;
  66. u32 type;
  67. u32 id;
  68. u32 flags;
  69. struct v4l2_fh *fh;
  70. struct list_head node;
  71. const struct v4l2_subscribed_event_ops *ops;
  72. unsigned int elems;
  73. unsigned int first;
  74. unsigned int in_use;
  75. struct v4l2_kevent events[];
  76. };
  77. /**
  78. * v4l2_event_dequeue - Dequeue events from video device.
  79. *
  80. * @fh: pointer to struct v4l2_fh
  81. * @event: pointer to struct v4l2_event
  82. * @nonblocking: if not zero, waits for an event to arrive
  83. */
  84. int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event,
  85. int nonblocking);
  86. /**
  87. * v4l2_event_queue - Queue events to video device.
  88. *
  89. * @vdev: pointer to &struct video_device
  90. * @ev: pointer to &struct v4l2_event
  91. *
  92. * The event will be queued for all &struct v4l2_fh file handlers.
  93. *
  94. * .. note::
  95. * The driver's only responsibility is to fill in the type and the data
  96. * fields. The other fields will be filled in by V4L2.
  97. */
  98. void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev);
  99. /**
  100. * v4l2_event_queue_fh - Queue events to video device.
  101. *
  102. * @fh: pointer to &struct v4l2_fh
  103. * @ev: pointer to &struct v4l2_event
  104. *
  105. *
  106. * The event will be queued only for the specified &struct v4l2_fh file handler.
  107. *
  108. * .. note::
  109. * The driver's only responsibility is to fill in the type and the data
  110. * fields. The other fields will be filled in by V4L2.
  111. */
  112. void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev);
  113. /**
  114. * v4l2_event_wake_all - Wake all filehandles.
  115. *
  116. * Used when unregistering a video device.
  117. *
  118. * @vdev: pointer to &struct video_device
  119. */
  120. void v4l2_event_wake_all(struct video_device *vdev);
  121. /**
  122. * v4l2_event_pending - Check if an event is available
  123. *
  124. * @fh: pointer to &struct v4l2_fh
  125. *
  126. * Returns the number of pending events.
  127. */
  128. int v4l2_event_pending(struct v4l2_fh *fh);
  129. /**
  130. * v4l2_event_subscribe - Subscribes to an event
  131. *
  132. * @fh: pointer to &struct v4l2_fh
  133. * @sub: pointer to &struct v4l2_event_subscription
  134. * @elems: size of the events queue
  135. * @ops: pointer to &v4l2_subscribed_event_ops
  136. *
  137. * .. note::
  138. *
  139. * if @elems is zero, the framework will fill in a default value,
  140. * with is currently 1 element.
  141. */
  142. int v4l2_event_subscribe(struct v4l2_fh *fh,
  143. const struct v4l2_event_subscription *sub,
  144. unsigned int elems,
  145. const struct v4l2_subscribed_event_ops *ops);
  146. /**
  147. * v4l2_event_unsubscribe - Unsubscribes to an event
  148. *
  149. * @fh: pointer to &struct v4l2_fh
  150. * @sub: pointer to &struct v4l2_event_subscription
  151. */
  152. int v4l2_event_unsubscribe(struct v4l2_fh *fh,
  153. const struct v4l2_event_subscription *sub);
  154. /**
  155. * v4l2_event_unsubscribe_all - Unsubscribes to all events
  156. *
  157. * @fh: pointer to &struct v4l2_fh
  158. */
  159. void v4l2_event_unsubscribe_all(struct v4l2_fh *fh);
  160. /**
  161. * v4l2_event_subdev_unsubscribe - Subdev variant of v4l2_event_unsubscribe()
  162. *
  163. * @sd: pointer to &struct v4l2_subdev
  164. * @fh: pointer to &struct v4l2_fh
  165. * @sub: pointer to &struct v4l2_event_subscription
  166. *
  167. * .. note::
  168. *
  169. * This function should be used for the &struct v4l2_subdev_core_ops
  170. * %unsubscribe_event field.
  171. */
  172. int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd,
  173. struct v4l2_fh *fh,
  174. struct v4l2_event_subscription *sub);
  175. /**
  176. * v4l2_src_change_event_subscribe - helper function that calls
  177. * v4l2_event_subscribe() if the event is %V4L2_EVENT_SOURCE_CHANGE.
  178. *
  179. * @fh: pointer to struct v4l2_fh
  180. * @sub: pointer to &struct v4l2_event_subscription
  181. */
  182. int v4l2_src_change_event_subscribe(struct v4l2_fh *fh,
  183. const struct v4l2_event_subscription *sub);
  184. /**
  185. * v4l2_src_change_event_subdev_subscribe - Variant of v4l2_event_subscribe(),
  186. * meant to subscribe only events of the type %V4L2_EVENT_SOURCE_CHANGE.
  187. *
  188. * @sd: pointer to &struct v4l2_subdev
  189. * @fh: pointer to &struct v4l2_fh
  190. * @sub: pointer to &struct v4l2_event_subscription
  191. */
  192. int v4l2_src_change_event_subdev_subscribe(struct v4l2_subdev *sd,
  193. struct v4l2_fh *fh,
  194. struct v4l2_event_subscription *sub);
  195. #endif /* V4L2_EVENT_H */