linux/include/media/v4l2-event.h

208 lines
6.2 KiB
C
Raw Normal View History

/*
* v4l2-event.h
*
* V4L2 events.
*
* Copyright (C) 2009--2010 Nokia Corporation.
*
* Contact: Sakari Ailus <sakari.ailus@iki.fi>
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* version 2 as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*/
#ifndef V4L2_EVENT_H
#define V4L2_EVENT_H
#include <linux/types.h>
#include <linux/videodev2.h>
#include <linux/wait.h>
struct v4l2_fh;
struct v4l2_subdev;
[media] v4l2-event/ctrls/fh: allocate events per fh and per type instead of just per-fh The driver had to decide how many events to allocate when the v4l2_fh struct was created. It was possible to add more events afterwards, but there was no way to ensure that you wouldn't miss important events if the event queue would fill up for that filehandle. In addition, once there were no more free events, any new events were simply dropped on the floor. For the control event in particular this made life very difficult since control status/value changes could just be missed if the number of allocated events and the speed at which the application read events was too low to keep up with the number of generated events. The application would have no idea what the latest state was for a control since it could have missed the latest control change. So this patch makes some major changes in how events are allocated. Instead of allocating events per-filehandle they are now allocated when subscribing an event. So for that particular event type N events (determined by the driver) are allocated. Those events are reserved for that particular event type. This ensures that you will not miss events for a particular type altogether. In addition, if there are N events in use and a new event is raised, then the oldest event is dropped and the new one is added. So the latest event is always available. This can be further improved by adding the ability to merge the state of two events together, ensuring that no data is lost at all. This will be added in the next patch. This also makes it possible to allow the user to determine the number of events that will be allocated. This is not implemented at the moment, but would be trivial. Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
2011-06-13 22:24:17 +00:00
struct v4l2_subscribed_event;
struct video_device;
/**
* struct v4l2_kevent - Internal kernel event struct.
* @list: List node for the v4l2_fh->available list.
* @sev: Pointer to parent v4l2_subscribed_event.
* @event: The event itself.
* @ts: The timestamp of the event.
*/
struct v4l2_kevent {
struct list_head list;
[media] v4l2-event/ctrls/fh: allocate events per fh and per type instead of just per-fh The driver had to decide how many events to allocate when the v4l2_fh struct was created. It was possible to add more events afterwards, but there was no way to ensure that you wouldn't miss important events if the event queue would fill up for that filehandle. In addition, once there were no more free events, any new events were simply dropped on the floor. For the control event in particular this made life very difficult since control status/value changes could just be missed if the number of allocated events and the speed at which the application read events was too low to keep up with the number of generated events. The application would have no idea what the latest state was for a control since it could have missed the latest control change. So this patch makes some major changes in how events are allocated. Instead of allocating events per-filehandle they are now allocated when subscribing an event. So for that particular event type N events (determined by the driver) are allocated. Those events are reserved for that particular event type. This ensures that you will not miss events for a particular type altogether. In addition, if there are N events in use and a new event is raised, then the oldest event is dropped and the new one is added. So the latest event is always available. This can be further improved by adding the ability to merge the state of two events together, ensuring that no data is lost at all. This will be added in the next patch. This also makes it possible to allow the user to determine the number of events that will be allocated. This is not implemented at the moment, but would be trivial. Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
2011-06-13 22:24:17 +00:00
struct v4l2_subscribed_event *sev;
struct v4l2_event event;
u64 ts;
};
/**
* struct v4l2_subscribed_event_ops - Subscribed event operations.
*
* @add: Optional callback, called when a new listener is added
* @del: Optional callback, called when a listener stops listening
* @replace: Optional callback that can replace event 'old' with event 'new'.
* @merge: Optional callback that can merge event 'old' into event 'new'.
*/
struct v4l2_subscribed_event_ops {
int (*add)(struct v4l2_subscribed_event *sev, unsigned int elems);
void (*del)(struct v4l2_subscribed_event *sev);
void (*replace)(struct v4l2_event *old, const struct v4l2_event *new);
void (*merge)(const struct v4l2_event *old, struct v4l2_event *new);
};
/**
* struct v4l2_subscribed_event - Internal struct representing a subscribed
* event.
*
* @list: List node for the v4l2_fh->subscribed list.
* @type: Event type.
* @id: Associated object ID (e.g. control ID). 0 if there isn't any.
* @flags: Copy of v4l2_event_subscription->flags.
* @fh: Filehandle that subscribed to this event.
* @node: List node that hooks into the object's event list
* (if there is one).
* @ops: v4l2_subscribed_event_ops
* @elems: The number of elements in the events array.
* @first: The index of the events containing the oldest available event.
* @in_use: The number of queued events.
* @events: An array of @elems events.
*/
struct v4l2_subscribed_event {
struct list_head list;
u32 type;
u32 id;
u32 flags;
struct v4l2_fh *fh;
struct list_head node;
const struct v4l2_subscribed_event_ops *ops;
unsigned int elems;
unsigned int first;
unsigned int in_use;
[media] v4l2-event/ctrls/fh: allocate events per fh and per type instead of just per-fh The driver had to decide how many events to allocate when the v4l2_fh struct was created. It was possible to add more events afterwards, but there was no way to ensure that you wouldn't miss important events if the event queue would fill up for that filehandle. In addition, once there were no more free events, any new events were simply dropped on the floor. For the control event in particular this made life very difficult since control status/value changes could just be missed if the number of allocated events and the speed at which the application read events was too low to keep up with the number of generated events. The application would have no idea what the latest state was for a control since it could have missed the latest control change. So this patch makes some major changes in how events are allocated. Instead of allocating events per-filehandle they are now allocated when subscribing an event. So for that particular event type N events (determined by the driver) are allocated. Those events are reserved for that particular event type. This ensures that you will not miss events for a particular type altogether. In addition, if there are N events in use and a new event is raised, then the oldest event is dropped and the new one is added. So the latest event is always available. This can be further improved by adding the ability to merge the state of two events together, ensuring that no data is lost at all. This will be added in the next patch. This also makes it possible to allow the user to determine the number of events that will be allocated. This is not implemented at the moment, but would be trivial. Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
2011-06-13 22:24:17 +00:00
struct v4l2_kevent events[];
};
/**
* v4l2_event_dequeue - Dequeue events from video device.
*
* @fh: pointer to struct v4l2_fh
* @event: pointer to struct v4l2_event
* @nonblocking: if not zero, waits for an event to arrive
*/
int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event,
int nonblocking);
/**
* v4l2_event_queue - Queue events to video device.
*
* @vdev: pointer to &struct video_device
* @ev: pointer to &struct v4l2_event
*
* The event will be queued for all &struct v4l2_fh file handlers.
*
* .. note::
* The driver's only responsibility is to fill in the type and the data
* fields.The other fields will be filled in by V4L2.
*/
void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev);
/**
* v4l2_event_queue_fh - Queue events to video device.
*
* @fh: pointer to &struct v4l2_fh
* @ev: pointer to &struct v4l2_event
*
*
* The event will be queued only for the specified &struct v4l2_fh file handler.
*
* .. note::
* The driver's only responsibility is to fill in the type and the data
* fields.The other fields will be filled in by V4L2.
*/
void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev);
/**
* v4l2_event_pending - Check if an event is available
*
* @fh: pointer to &struct v4l2_fh
*
* Returns the number of pending events.
*/
int v4l2_event_pending(struct v4l2_fh *fh);
/**
* v4l2_event_subscribe - Subscribes to an event
*
* @fh: pointer to &struct v4l2_fh
* @sub: pointer to &struct v4l2_event_subscription
* @elems: size of the events queue
* @ops: pointer to &v4l2_subscribed_event_ops
*
* .. note::
*
* if @elems is zero, the framework will fill in a default value,
* with is currently 1 element.
*/
int v4l2_event_subscribe(struct v4l2_fh *fh,
const struct v4l2_event_subscription *sub,
unsigned int elems,
const struct v4l2_subscribed_event_ops *ops);
/**
* v4l2_event_unsubscribe - Unsubscribes to an event
*
* @fh: pointer to &struct v4l2_fh
* @sub: pointer to &struct v4l2_event_subscription
*/
int v4l2_event_unsubscribe(struct v4l2_fh *fh,
const struct v4l2_event_subscription *sub);
/**
* v4l2_event_unsubscribe_all - Unsubscribes to all events
*
* @fh: pointer to &struct v4l2_fh
*/
[media] v4l2-event/ctrls/fh: allocate events per fh and per type instead of just per-fh The driver had to decide how many events to allocate when the v4l2_fh struct was created. It was possible to add more events afterwards, but there was no way to ensure that you wouldn't miss important events if the event queue would fill up for that filehandle. In addition, once there were no more free events, any new events were simply dropped on the floor. For the control event in particular this made life very difficult since control status/value changes could just be missed if the number of allocated events and the speed at which the application read events was too low to keep up with the number of generated events. The application would have no idea what the latest state was for a control since it could have missed the latest control change. So this patch makes some major changes in how events are allocated. Instead of allocating events per-filehandle they are now allocated when subscribing an event. So for that particular event type N events (determined by the driver) are allocated. Those events are reserved for that particular event type. This ensures that you will not miss events for a particular type altogether. In addition, if there are N events in use and a new event is raised, then the oldest event is dropped and the new one is added. So the latest event is always available. This can be further improved by adding the ability to merge the state of two events together, ensuring that no data is lost at all. This will be added in the next patch. This also makes it possible to allow the user to determine the number of events that will be allocated. This is not implemented at the moment, but would be trivial. Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
2011-06-13 22:24:17 +00:00
void v4l2_event_unsubscribe_all(struct v4l2_fh *fh);
/**
* v4l2_event_subdev_unsubscribe - Subdev variant of v4l2_event_unsubscribe()
*
* @sd: pointer to &struct v4l2_subdev
* @fh: pointer to &struct v4l2_fh
* @sub: pointer to &struct v4l2_event_subscription
*
* .. note::
*
* This function should be used for the &struct v4l2_subdev_core_ops
* %unsubscribe_event field.
*/
int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd,
struct v4l2_fh *fh,
struct v4l2_event_subscription *sub);
/**
[media] get rid of a number of problems at the cross references As warned by linuxdoc[1] tool, using: $ for i in $(git grep kernel-doc Documentation/media/kapi/|cut -d: -f4); do kernel-lintdoc --sloppy $i; done include/media/v4l2-dev.h:118 :WARN: function name from comment differs: v4l2_prio_close <--> v4l2_prio_check include/media/v4l2-mc.h:56 [kernel-doc WARN] : enum name from comment differs: if_vid_dec_index <--> if_vid_dec_pad_index include/media/v4l2-mc.h:71 [kernel-doc WARN] : enum name from comment differs: if_aud_dec_index <--> if_aud_dec_pad_index include/media/v4l2-mem2mem.h:396 [kernel-doc WARN] : function name from comment differs: v4l2_m2m_num_src_bufs_ready <--> v4l2_m2m_num_dst_bufs_ready drivers/media/dvb-core/dvb_math.h:28 [kernel-doc WARN] : function name from comment differs: cintlog2 <--> intlog2 include/media/v4l2-subdev.h:215 [kernel-doc WARN] : struct name from comment differs: s_radio <--> v4l2_subdev_tuner_ops include/media/v4l2-subdev.h:890 [kernel-doc WARN] : function name from comment differs: v4l2_set_subdevdata <--> v4l2_set_subdev_hostdata include/media/v4l2-subdev.h:901 [kernel-doc WARN] : function name from comment differs: v4l2_get_subdevdata <--> v4l2_get_subdev_hostdata drivers/media/dvb-core/dvb_ringbuffer.h:196 [kernel-doc WARN] : function name from comment differs: dvb_ringbuffer_writeuser <--> dvb_ringbuffer_write_user include/media/videobuf2-core.h:399 [kernel-doc WARN] : struct name from comment differs: vb2_ops <--> vb2_buf_ops include/media/media-entity.h:132 [kernel-doc ERROR] : duplicate parameter definition 'source' include/media/media-entity.h:477 [kernel-doc WARN] : function name from comment differs: media_entity_enum_test <--> media_entity_enum_test_and_set include/media/media-entity.h:535 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> gobj_to_pad include/media/media-entity.h:544 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> gobj_to_link include/media/media-entity.h:553 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> gobj_to_intf include/media/media-entity.h:562 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> intf_to_devnode include/media/rc-core.h:234 [kernel-doc WARN] : function name from comment differs: rc_open <--> rc_close include/media/v4l2-ctrls.h:397 [kernel-doc WARN] : missing initial short description of 'v4l2_ctrl_handler_init' include/media/v4l2-dev.h:118 [kernel-doc WARN] : function name from comment differs: v4l2_prio_close <--> v4l2_prio_check include/media/v4l2-event.h:225 [kernel-doc WARN] : missing initial short description of 'v4l2_src_change_event_subscribe' [1] https://return42.github.io/linuxdoc/linux.html The above are real issues at the documentation. On several cases, caused by cut-and-paste. Fix them. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-22 10:59:03 +00:00
* v4l2_src_change_event_subscribe - helper function that calls
* v4l2_event_subscribe() if the event is %V4L2_EVENT_SOURCE_CHANGE.
*
* @fh: pointer to struct v4l2_fh
* @sub: pointer to &struct v4l2_event_subscription
*/
int v4l2_src_change_event_subscribe(struct v4l2_fh *fh,
const struct v4l2_event_subscription *sub);
/**
* v4l2_src_change_event_subdev_subscribe - Variant of v4l2_event_subscribe(),
* meant to subscribe only events of the type %V4L2_EVENT_SOURCE_CHANGE.
*
* @sd: pointer to &struct v4l2_subdev
* @fh: pointer to &struct v4l2_fh
* @sub: pointer to &struct v4l2_event_subscription
*/
int v4l2_src_change_event_subdev_subscribe(struct v4l2_subdev *sd,
struct v4l2_fh *fh,
struct v4l2_event_subscription *sub);
#endif /* V4L2_EVENT_H */