[media] v4l2-framework.txt: update v4l2_event section

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

[media] v4l2-framework.txt: update v4l2_event section
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Hans Verkuil · Mauro Carvalho Chehab
1 parent 98019f5e88
Showing 1 changed file with 35 additions and 16 deletions Side-by-side Diff
Documentation/video4linux/v4l2-framework.txt
@@ -897,15 +897,39 @@
 The V4L2 events provide a generic way to pass events to user space.
 The driver must use v4l2_fh to be able to support V4L2 events.
  
-Useful functions:
+Events are defined by a type and an optional ID. The ID may refer to a V4L2
+object such as a control ID. If unused, then the ID is 0.
  
-- v4l2_event_alloc()
+When the user subscribes to an event the driver will allocate a number of
+kevent structs for that event. So every (type, ID) event tuple will have
+its own set of kevent structs. This guarantees that if a driver is generating
+lots of events of one type in a short time, then that will not overwrite
+events of another type.
  
-  To use events, the driver must allocate events for the file handle. By
-  calling the function more than once, the driver may assure that at least n
-  events in total have been allocated. The function may not be called in
-  atomic context.
+But if you get more events of one type than the number of kevents that were
+reserved, then the oldest event will be dropped and the new one added.
  
+Furthermore, the internal struct v4l2_subscribed_event has merge() and
+replace() callbacks which drivers can set. These callbacks are called when
+a new event is raised and there is no more room. The replace() callback
+allows you to replace the payload of the old event with that of the new event,
+merging any relevant data from the old payload into the new payload that
+replaces it. It is called when this event type has only one kevent struct
+allocated. The merge() callback allows you to merge the oldest event payload
+into that of the second-oldest event payload. It is called when there are two
+or more kevent structs allocated.
+
+This way no status information is lost, just the intermediate steps leading
+up to that state.
+
+A good example of these replace/merge callbacks is in v4l2-event.c:
+ctrls_replace() and ctrls_merge() callbacks for the control event.
+
+Note: these callbacks can be called from interrupt context, so they must be
+fast.
+
+Useful functions:
+
 - v4l2_event_queue()
  
   Queue events to video device. The driver's only responsibility is to fill
@@ -916,7 +940,9 @@
  
   The video_device->ioctl_ops->vidioc_subscribe_event must check the driver
   is able to produce events with specified event id. Then it calls
-  v4l2_event_subscribe() to subscribe the event.
+  v4l2_event_subscribe() to subscribe the event. The last argument is the
+  size of the event queue for this event. If it is 0, then the framework
+  will fill in a default value (this depends on the event type).
  
 - v4l2_event_unsubscribe()
  
  
@@ -931,14 +957,8 @@
  
   Returns the number of pending events. Useful when implementing poll.
  
-Drivers do not initialise events directly. The events are initialised
-through v4l2_fh_init() if video_device->ioctl_ops->vidioc_subscribe_event is
-non-NULL. This *MUST* be performed in the driver's
-v4l2_file_operations->open() handler.
-
 Events are delivered to user space through the poll system call. The driver
-can use v4l2_fh->events->wait wait_queue_head_t as the argument for
-poll_wait().
+can use v4l2_fh->wait (a wait_queue_head_t) as the argument for poll_wait().
  
 There are standard and private events. New standard events must use the
 smallest available event type. The drivers must allocate their events from
@@ -948,6 +968,5 @@
 available event type is 'class base + 1'.
  
 An example on how the V4L2 events may be used can be found in the OMAP
-3 ISP driver available at <URL:http://gitorious.org/omap3camera> as of
-writing this.
+3 ISP driver (drivers/media/video/omap3isp).
...	...	@@ -897,15 +897,39 @@
897	897	The V4L2 events provide a generic way to pass events to user space.
898	898	The driver must use v4l2_fh to be able to support V4L2 events.
899	899
900		-Useful functions:
	900	+Events are defined by a type and an optional ID. The ID may refer to a V4L2
	901	+object such as a control ID. If unused, then the ID is 0.
901	902
902		-- v4l2_event_alloc()
	903	+When the user subscribes to an event the driver will allocate a number of
	904	+kevent structs for that event. So every (type, ID) event tuple will have
	905	+its own set of kevent structs. This guarantees that if a driver is generating
	906	+lots of events of one type in a short time, then that will not overwrite
	907	+events of another type.
903	908
904		- To use events, the driver must allocate events for the file handle. By
905		- calling the function more than once, the driver may assure that at least n
906		- events in total have been allocated. The function may not be called in
907		- atomic context.
	909	+But if you get more events of one type than the number of kevents that were
	910	+reserved, then the oldest event will be dropped and the new one added.
908	911
	912	+Furthermore, the internal struct v4l2_subscribed_event has merge() and
	913	+replace() callbacks which drivers can set. These callbacks are called when
	914	+a new event is raised and there is no more room. The replace() callback
	915	+allows you to replace the payload of the old event with that of the new event,
	916	+merging any relevant data from the old payload into the new payload that
	917	+replaces it. It is called when this event type has only one kevent struct
	918	+allocated. The merge() callback allows you to merge the oldest event payload
	919	+into that of the second-oldest event payload. It is called when there are two
	920	+or more kevent structs allocated.
	921	+
	922	+This way no status information is lost, just the intermediate steps leading
	923	+up to that state.
	924	+
	925	+A good example of these replace/merge callbacks is in v4l2-event.c:
	926	+ctrls_replace() and ctrls_merge() callbacks for the control event.
	927	+
	928	+Note: these callbacks can be called from interrupt context, so they must be
	929	+fast.
	930	+
	931	+Useful functions:
	932	+
909	933	- v4l2_event_queue()
910	934
911	935	Queue events to video device. The driver's only responsibility is to fill
...	...	@@ -916,7 +940,9 @@
916	940
917	941	The video_device->ioctl_ops->vidioc_subscribe_event must check the driver
918	942	is able to produce events with specified event id. Then it calls
919		- v4l2_event_subscribe() to subscribe the event.
	943	+ v4l2_event_subscribe() to subscribe the event. The last argument is the
	944	+ size of the event queue for this event. If it is 0, then the framework
	945	+ will fill in a default value (this depends on the event type).
920	946
921	947	- v4l2_event_unsubscribe()
922	948
923	949
...	...	@@ -931,14 +957,8 @@
931	957
932	958	Returns the number of pending events. Useful when implementing poll.
933	959
934		-Drivers do not initialise events directly. The events are initialised
935		-through v4l2_fh_init() if video_device->ioctl_ops->vidioc_subscribe_event is
936		-non-NULL. This MUST be performed in the driver's
937		-v4l2_file_operations->open() handler.
938		-
939	960	Events are delivered to user space through the poll system call. The driver
940		-can use v4l2_fh->events->wait wait_queue_head_t as the argument for
941		-poll_wait().
	961	+can use v4l2_fh->wait (a wait_queue_head_t) as the argument for poll_wait().
942	962
943	963	There are standard and private events. New standard events must use the
944	964	smallest available event type. The drivers must allocate their events from
...	...	@@ -948,6 +968,5 @@
948	968	available event type is 'class base + 1'.
949	969
950	970	An example on how the V4L2 events may be used can be found in the OMAP
951		-3 ISP driver available at <URL:http://gitorious.org/omap3camera> as of
952		-writing this.
	971	+3 ISP driver (drivers/media/video/omap3isp).