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