include/media/v4l2-event.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * v4l2-event.h
0004  *
0005  * V4L2 events.
0006  *
0007  * Copyright (C) 2009--2010 Nokia Corporation.
0008  *
0009  * Contact: Sakari Ailus <sakari.ailus@iki.fi>
0010  */
0011
0012 #ifndef V4L2_EVENT_H
0013 #define V4L2_EVENT_H
0014
0015 #include <linux/types.h>
0016 #include <linux/videodev2.h>
0017 #include <linux/wait.h>
0018
0019 struct v4l2_fh;
0020 struct v4l2_subdev;
0021 struct v4l2_subscribed_event;
0022 struct video_device;
0023
0024 /**
0025  * struct v4l2_kevent - Internal kernel event struct.
0026  * @list:   List node for the v4l2_fh->available list.
0027  * @sev:    Pointer to parent v4l2_subscribed_event.
0028  * @event:  The event itself.
0029  * @ts:     The timestamp of the event.
0030  */
0031 struct v4l2_kevent {
0032     struct list_head    list;
0033     struct v4l2_subscribed_event *sev;
0034     struct v4l2_event   event;
0035     u64         ts;
0036 };
0037
0038 /**
0039  * struct v4l2_subscribed_event_ops - Subscribed event operations.
0040  *
0041  * @add:    Optional callback, called when a new listener is added
0042  * @del:    Optional callback, called when a listener stops listening
0043  * @replace:    Optional callback that can replace event 'old' with event 'new'.
0044  * @merge:  Optional callback that can merge event 'old' into event 'new'.
0045  */
0046 struct v4l2_subscribed_event_ops {
0047     int  (*add)(struct v4l2_subscribed_event *sev, unsigned int elems);
0048     void (*del)(struct v4l2_subscribed_event *sev);
0049     void (*replace)(struct v4l2_event *old, const struct v4l2_event *new);
0050     void (*merge)(const struct v4l2_event *old, struct v4l2_event *new);
0051 };
0052
0053 /**
0054  * struct v4l2_subscribed_event - Internal struct representing a subscribed
0055  *      event.
0056  *
0057  * @list:   List node for the v4l2_fh->subscribed list.
0058  * @type:   Event type.
0059  * @id: Associated object ID (e.g. control ID). 0 if there isn't any.
0060  * @flags:  Copy of v4l2_event_subscription->flags.
0061  * @fh: Filehandle that subscribed to this event.
0062  * @node:   List node that hooks into the object's event list
0063  *      (if there is one).
0064  * @ops:    v4l2_subscribed_event_ops
0065  * @elems:  The number of elements in the events array.
0066  * @first:  The index of the events containing the oldest available event.
0067  * @in_use: The number of queued events.
0068  * @events: An array of @elems events.
0069  */
0070 struct v4l2_subscribed_event {
0071     struct list_head    list;
0072     u32         type;
0073     u32         id;
0074     u32         flags;
0075     struct v4l2_fh      *fh;
0076     struct list_head    node;
0077     const struct v4l2_subscribed_event_ops *ops;
0078     unsigned int        elems;
0079     unsigned int        first;
0080     unsigned int        in_use;
0081     struct v4l2_kevent  events[];
0082 };
0083
0084 /**
0085  * v4l2_event_dequeue - Dequeue events from video device.
0086  *
0087  * @fh: pointer to struct v4l2_fh
0088  * @event: pointer to struct v4l2_event
0089  * @nonblocking: if not zero, waits for an event to arrive
0090  */
0091 int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event,
0092                int nonblocking);
0093
0094 /**
0095  * v4l2_event_queue - Queue events to video device.
0096  *
0097  * @vdev: pointer to &struct video_device
0098  * @ev: pointer to &struct v4l2_event
0099  *
0100  * The event will be queued for all &struct v4l2_fh file handlers.
0101  *
0102  * .. note::
0103  *    The driver's only responsibility is to fill in the type and the data
0104  *    fields. The other fields will be filled in by V4L2.
0105  */
0106 void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev);
0107
0108 /**
0109  * v4l2_event_queue_fh - Queue events to video device.
0110  *
0111  * @fh: pointer to &struct v4l2_fh
0112  * @ev: pointer to &struct v4l2_event
0113  *
0114  *
0115  * The event will be queued only for the specified &struct v4l2_fh file handler.
0116  *
0117  * .. note::
0118  *    The driver's only responsibility is to fill in the type and the data
0119  *    fields. The other fields will be filled in by V4L2.
0120  */
0121 void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev);
0122
0123 /**
0124  * v4l2_event_wake_all - Wake all filehandles.
0125  *
0126  * Used when unregistering a video device.
0127  *
0128  * @vdev: pointer to &struct video_device
0129  */
0130 void v4l2_event_wake_all(struct video_device *vdev);
0131
0132 /**
0133  * v4l2_event_pending - Check if an event is available
0134  *
0135  * @fh: pointer to &struct v4l2_fh
0136  *
0137  * Returns the number of pending events.
0138  */
0139 int v4l2_event_pending(struct v4l2_fh *fh);
0140
0141 /**
0142  * v4l2_event_subscribe - Subscribes to an event
0143  *
0144  * @fh: pointer to &struct v4l2_fh
0145  * @sub: pointer to &struct v4l2_event_subscription
0146  * @elems: size of the events queue
0147  * @ops: pointer to &v4l2_subscribed_event_ops
0148  *
0149  * .. note::
0150  *
0151  *    if @elems is zero, the framework will fill in a default value,
0152  *    with is currently 1 element.
0153  */
0154 int v4l2_event_subscribe(struct v4l2_fh *fh,
0155              const struct v4l2_event_subscription *sub,
0156              unsigned int elems,
0157              const struct v4l2_subscribed_event_ops *ops);
0158 /**
0159  * v4l2_event_unsubscribe - Unsubscribes to an event
0160  *
0161  * @fh: pointer to &struct v4l2_fh
0162  * @sub: pointer to &struct v4l2_event_subscription
0163  */
0164 int v4l2_event_unsubscribe(struct v4l2_fh *fh,
0165                const struct v4l2_event_subscription *sub);
0166 /**
0167  * v4l2_event_unsubscribe_all - Unsubscribes to all events
0168  *
0169  * @fh: pointer to &struct v4l2_fh
0170  */
0171 void v4l2_event_unsubscribe_all(struct v4l2_fh *fh);
0172
0173 /**
0174  * v4l2_event_subdev_unsubscribe - Subdev variant of v4l2_event_unsubscribe()
0175  *
0176  * @sd: pointer to &struct v4l2_subdev
0177  * @fh: pointer to &struct v4l2_fh
0178  * @sub: pointer to &struct v4l2_event_subscription
0179  *
0180  * .. note::
0181  *
0182  *  This function should be used for the &struct v4l2_subdev_core_ops
0183  *  %unsubscribe_event field.
0184  */
0185 int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd,
0186                   struct v4l2_fh *fh,
0187                   struct v4l2_event_subscription *sub);
0188 /**
0189  * v4l2_src_change_event_subscribe - helper function that calls
0190  *  v4l2_event_subscribe() if the event is %V4L2_EVENT_SOURCE_CHANGE.
0191  *
0192  * @fh: pointer to struct v4l2_fh
0193  * @sub: pointer to &struct v4l2_event_subscription
0194  */
0195 int v4l2_src_change_event_subscribe(struct v4l2_fh *fh,
0196                     const struct v4l2_event_subscription *sub);
0197 /**
0198  * v4l2_src_change_event_subdev_subscribe - Variant of v4l2_event_subscribe(),
0199  *  meant to subscribe only events of the type %V4L2_EVENT_SOURCE_CHANGE.
0200  *
0201  * @sd: pointer to &struct v4l2_subdev
0202  * @fh: pointer to &struct v4l2_fh
0203  * @sub: pointer to &struct v4l2_event_subscription
0204  */
0205 int v4l2_src_change_event_subdev_subscribe(struct v4l2_subdev *sd,
0206                        struct v4l2_fh *fh,
0207                        struct v4l2_event_subscription *sub);
0208 #endif /* V4L2_EVENT_H */