[mirror_ubuntu-artful-kernel.git] / Documentation / media / uapi / v4l / dev-event.rst

.. -*- coding: utf-8; mode: rst -*-

.. _event:

***************
Event Interface
***************

The V4L2 event interface provides a means for a user to get immediately
notified on certain conditions taking place on a device. This might
include start of frame or loss of signal events, for example. Changes in
the value or state of a V4L2 control can also be reported through
events.

To receive events, the events the user is interested in first must be
subscribed using the
:ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once
an event is subscribed, the events of subscribed types are dequeueable
using the :ref:`VIDIOC_DQEVENT` ioctl. Events may be
unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event
type V4L2_EVENT_ALL may be used to unsubscribe all the events the
driver supports.

The event subscriptions and event queues are specific to file handles.
Subscribing an event on one file handle does not affect other file
handles.

The information on dequeueable events is obtained by using select or
poll system calls on video devices. The V4L2 events use POLLPRI events
on poll system call and exceptions on select system call.

Starting with kernel 3.1 certain guarantees can be given with regards to
events:

1. Each subscribed event has its own internal dedicated event queue.
   This means that flooding of one event type will not interfere with
   other event types.

2. If the internal event queue for a particular subscribed event becomes
   full, then the oldest event in that queue will be dropped.

3. Where applicable, certain event types can ensure that the payload of
   the oldest event that is about to be dropped will be merged with the
   payload of the next oldest event. Thus ensuring that no information
   is lost, but only an intermediate step leading up to that
   information. See the documentation for the event you want to
   subscribe to whether this is applicable for that event or not.
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
	2
	3	.. _event:
	4
	5	***************
	6	Event Interface
	7	***************
	8
	9	The V4L2 event interface provides a means for a user to get immediately
	10	notified on certain conditions taking place on a device. This might
	11	include start of frame or loss of signal events, for example. Changes in
	12	the value or state of a V4L2 control can also be reported through
	13	events.
	14
	15	To receive events, the events the user is interested in first must be
	16	subscribed using the
7347081e	17	:ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once
5377d91f	18	an event is subscribed, the events of subscribed types are dequeueable
7347081e	19	using the :ref:`VIDIOC_DQEVENT` ioctl. Events may be
5377d91f MH	20	unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event
	21	type V4L2_EVENT_ALL may be used to unsubscribe all the events the
	22	driver supports.
	23
	24	The event subscriptions and event queues are specific to file handles.
	25	Subscribing an event on one file handle does not affect other file
	26	handles.
	27
	28	The information on dequeueable events is obtained by using select or
	29	poll system calls on video devices. The V4L2 events use POLLPRI events
	30	on poll system call and exceptions on select system call.
	31
	32	Starting with kernel 3.1 certain guarantees can be given with regards to
	33	events:
	34
	35	1. Each subscribed event has its own internal dedicated event queue.
	36	This means that flooding of one event type will not interfere with
	37	other event types.
	38
	39	2. If the internal event queue for a particular subscribed event becomes
	40	full, then the oldest event in that queue will be dropped.
	41
	42	3. Where applicable, certain event types can ensure that the payload of
	43	the oldest event that is about to be dropped will be merged with the
	44	payload of the next oldest event. Thus ensuring that no information
	45	is lost, but only an intermediate step leading up to that
	46	information. See the documentation for the event you want to
	47	subscribe to whether this is applicable for that event or not.