blob: 6741910c3a18978cfd7fd2dc295a4a11ea680538 [file] [log] [blame]
Sakari Ailusc3b5b022010-03-01 05:14:18 -03001/*
2 * v4l2-event.h
3 *
4 * V4L2 events.
5 *
6 * Copyright (C) 2009--2010 Nokia Corporation.
7 *
Sakari Ailus8c5dff92012-10-28 06:44:17 -03008 * Contact: Sakari Ailus <sakari.ailus@iki.fi>
Sakari Ailusc3b5b022010-03-01 05:14:18 -03009 *
10 * This program is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU General Public License
12 * version 2 as published by the Free Software Foundation.
13 *
14 * This program is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * General Public License for more details.
Sakari Ailusc3b5b022010-03-01 05:14:18 -030018 */
19
20#ifndef V4L2_EVENT_H
21#define V4L2_EVENT_H
22
23#include <linux/types.h>
24#include <linux/videodev2.h>
25#include <linux/wait.h>
26
Hans Verkuil3ad57c32011-06-20 12:00:36 -030027/*
28 * Overview:
29 *
30 * Events are subscribed per-filehandle. An event specification consists of a
31 * type and is optionally associated with an object identified through the
32 * 'id' field. So an event is uniquely identified by the (type, id) tuple.
33 *
34 * The v4l2-fh struct has a list of subscribed events. The v4l2_subscribed_event
35 * struct is added to that list, one for every subscribed event.
36 *
37 * Each v4l2_subscribed_event struct ends with an array of v4l2_kevent structs.
38 * This array (ringbuffer, really) is used to store any events raised by the
39 * driver. The v4l2_kevent struct links into the 'available' list of the
40 * v4l2_fh struct so VIDIOC_DQEVENT will know which event to dequeue first.
41 *
42 * Finally, if the event subscription is associated with a particular object
43 * such as a V4L2 control, then that object needs to know about that as well
44 * so that an event can be raised by that object. So the 'node' field can
45 * be used to link the v4l2_subscribed_event struct into a list of that
46 * object.
47 *
48 * So to summarize:
49 *
50 * struct v4l2_fh has two lists: one of the subscribed events, and one of the
51 * pending events.
52 *
53 * struct v4l2_subscribed_event has a ringbuffer of raised (pending) events of
54 * that particular type.
55 *
56 * If struct v4l2_subscribed_event is associated with a specific object, then
57 * that object will have an internal list of struct v4l2_subscribed_event so
58 * it knows who subscribed an event to that object.
59 */
60
Sakari Ailusc3b5b022010-03-01 05:14:18 -030061struct v4l2_fh;
Sylwester Nawrocki4f4d14b2013-01-22 18:58:57 -030062struct v4l2_subdev;
Hans Verkuilf1e393d2011-06-13 19:24:17 -030063struct v4l2_subscribed_event;
Sakari Ailusc3b5b022010-03-01 05:14:18 -030064struct video_device;
65
Mauro Carvalho Chehabb6fce852015-08-22 08:28:39 -030066/**
67 * struct v4l2_kevent - Internal kernel event struct.
68 * @list: List node for the v4l2_fh->available list.
69 * @sev: Pointer to parent v4l2_subscribed_event.
70 * @event: The event itself.
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -030071 */
Sakari Ailusc3b5b022010-03-01 05:14:18 -030072struct v4l2_kevent {
73 struct list_head list;
Hans Verkuilf1e393d2011-06-13 19:24:17 -030074 struct v4l2_subscribed_event *sev;
Sakari Ailusc3b5b022010-03-01 05:14:18 -030075 struct v4l2_event event;
76};
77
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -030078/**
79 * struct v4l2_subscribed_event_ops - Subscribed event operations.
Mauro Carvalho Chehabb6fce852015-08-22 08:28:39 -030080 *
81 * @add: Optional callback, called when a new listener is added
82 * @del: Optional callback, called when a listener stops listening
83 * @replace: Optional callback that can replace event 'old' with event 'new'.
84 * @merge: Optional callback that can merge event 'old' into event 'new'.
85 */
Hans de Goedec53c2542012-04-08 12:59:46 -030086struct v4l2_subscribed_event_ops {
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -030087 int (*add)(struct v4l2_subscribed_event *sev, unsigned int elems);
Hans de Goedec53c2542012-04-08 12:59:46 -030088 void (*del)(struct v4l2_subscribed_event *sev);
89 void (*replace)(struct v4l2_event *old, const struct v4l2_event *new);
90 void (*merge)(const struct v4l2_event *old, struct v4l2_event *new);
91};
92
Mauro Carvalho Chehabb6fce852015-08-22 08:28:39 -030093/**
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -030094 * struct v4l2_subscribed_event - Internal struct representing a subscribed
95 * event.
96 *
Mauro Carvalho Chehabb6fce852015-08-22 08:28:39 -030097 * @list: List node for the v4l2_fh->subscribed list.
98 * @type: Event type.
99 * @id: Associated object ID (e.g. control ID). 0 if there isn't any.
100 * @flags: Copy of v4l2_event_subscription->flags.
101 * @fh: Filehandle that subscribed to this event.
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300102 * @node: List node that hooks into the object's event list
103 * (if there is one).
Mauro Carvalho Chehabb6fce852015-08-22 08:28:39 -0300104 * @ops: v4l2_subscribed_event_ops
105 * @elems: The number of elements in the events array.
106 * @first: The index of the events containing the oldest available event.
107 * @in_use: The number of queued events.
108 * @events: An array of @elems events.
109 */
Sakari Ailusc3b5b022010-03-01 05:14:18 -0300110struct v4l2_subscribed_event {
111 struct list_head list;
112 u32 type;
Hans Verkuil6e239392011-06-07 11:13:44 -0300113 u32 id;
Hans Verkuil77068d32011-06-13 18:55:58 -0300114 u32 flags;
Hans Verkuil77068d32011-06-13 18:55:58 -0300115 struct v4l2_fh *fh;
Hans Verkuil77068d32011-06-13 18:55:58 -0300116 struct list_head node;
Hans de Goedec53c2542012-04-08 12:59:46 -0300117 const struct v4l2_subscribed_event_ops *ops;
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300118 unsigned int elems;
119 unsigned int first;
120 unsigned int in_use;
Hans Verkuilf1e393d2011-06-13 19:24:17 -0300121 struct v4l2_kevent events[];
Sakari Ailusc3b5b022010-03-01 05:14:18 -0300122};
123
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300124/**
125 * v4l2_event_dequeue - Dequeue events from video device.
126 *
127 * @fh: pointer to struct v4l2_fh
128 * @event: pointer to struct v4l2_event
129 * @nonblocking: if not zero, waits for an event to arrive
130 */
Sakari Ailusc3b5b022010-03-01 05:14:18 -0300131int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event,
132 int nonblocking);
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300133
134/**
135 * v4l2_event_queue - Queue events to video device.
136 *
137 * @vdev: pointer to &struct video_device
138 * @ev: pointer to &struct v4l2_event
139 *
140 * The event will be queued for all &struct v4l2_fh file handlers.
141 *
142 * .. note::
143 * The driver's only responsibility is to fill in the type and the data
144 * fields.The other fields will be filled in by V4L2.
145 */
Sakari Ailusc3b5b022010-03-01 05:14:18 -0300146void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev);
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300147
148/**
149 * v4l2_event_queue_fh - Queue events to video device.
150 *
151 * @fh: pointer to &struct v4l2_fh
152 * @ev: pointer to &struct v4l2_event
153 *
154 *
155 * The event will be queued only for the specified &struct v4l2_fh file handler.
156 *
157 * .. note::
158 * The driver's only responsibility is to fill in the type and the data
159 * fields.The other fields will be filled in by V4L2.
160 */
Hans Verkuil6e239392011-06-07 11:13:44 -0300161void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev);
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300162
163/**
164 * v4l2_event_pending - Check if an event is available
165 *
166 * @fh: pointer to &struct v4l2_fh
167 *
168 * Returns the number of pending events.
169 */
Sakari Ailusc3b5b022010-03-01 05:14:18 -0300170int v4l2_event_pending(struct v4l2_fh *fh);
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300171
172/**
173 * v4l2_event_subscribe - Subscribes to an event
174 *
175 * @fh: pointer to &struct v4l2_fh
176 * @sub: pointer to &struct v4l2_event_subscription
177 * @elems: size of the events queue
178 * @ops: pointer to &v4l2_subscribed_event_ops
179 *
180 * .. note::
181 *
182 * if @elems is zero, the framework will fill in a default value,
183 * with is currently 1 element.
184 */
Sakari Ailusc3b5b022010-03-01 05:14:18 -0300185int v4l2_event_subscribe(struct v4l2_fh *fh,
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300186 const struct v4l2_event_subscription *sub,
187 unsigned int elems,
Hans de Goedec53c2542012-04-08 12:59:46 -0300188 const struct v4l2_subscribed_event_ops *ops);
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300189/**
190 * v4l2_event_unsubscribe - Unsubscribes to an event
191 *
192 * @fh: pointer to &struct v4l2_fh
193 * @sub: pointer to &struct v4l2_event_subscription
194 */
Sakari Ailusc3b5b022010-03-01 05:14:18 -0300195int v4l2_event_unsubscribe(struct v4l2_fh *fh,
Hans Verkuil85f5fe32012-09-04 11:46:09 -0300196 const struct v4l2_event_subscription *sub);
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300197/**
198 * v4l2_event_unsubscribe_all - Unsubscribes to all events
199 *
200 * @fh: pointer to &struct v4l2_fh
201 */
Hans Verkuilf1e393d2011-06-13 19:24:17 -0300202void v4l2_event_unsubscribe_all(struct v4l2_fh *fh);
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300203
204/**
205 * v4l2_event_subdev_unsubscribe - Subdev variant of v4l2_event_unsubscribe()
206 *
207 * @sd: pointer to &struct v4l2_subdev
208 * @fh: pointer to &struct v4l2_fh
209 * @sub: pointer to &struct v4l2_event_subscription
210 *
211 * .. note::
212 *
213 * This function should be used for the &struct v4l2_subdev_core_ops
214 * %unsubscribe_event field.
215 */
216int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd,
217 struct v4l2_fh *fh,
Sylwester Nawrocki4f4d14b2013-01-22 18:58:57 -0300218 struct v4l2_event_subscription *sub);
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300219/**
Mauro Carvalho Chehabe383ce02016-09-22 07:59:03 -0300220 * v4l2_src_change_event_subscribe - helper function that calls
221 * v4l2_event_subscribe() if the event is %V4L2_EVENT_SOURCE_CHANGE.
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300222 *
223 * @fh: pointer to struct v4l2_fh
224 * @sub: pointer to &struct v4l2_event_subscription
225 */
Arun Kumar K3cbe6e52014-05-14 03:59:42 -0300226int v4l2_src_change_event_subscribe(struct v4l2_fh *fh,
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300227 const struct v4l2_event_subscription *sub);
228/**
229 * v4l2_src_change_event_subdev_subscribe - Variant of v4l2_event_subscribe(),
230 * meant to subscribe only events of the type %V4L2_EVENT_SOURCE_CHANGE.
231 *
232 * @sd: pointer to &struct v4l2_subdev
233 * @fh: pointer to &struct v4l2_fh
234 * @sub: pointer to &struct v4l2_event_subscription
235 */
Arun Kumar K3cbe6e52014-05-14 03:59:42 -0300236int v4l2_src_change_event_subdev_subscribe(struct v4l2_subdev *sd,
Mauro Carvalho Chehab9d4ee1a2016-07-22 07:27:06 -0300237 struct v4l2_fh *fh,
238 struct v4l2_event_subscription *sub);
Sakari Ailusc3b5b022010-03-01 05:14:18 -0300239#endif /* V4L2_EVENT_H */