-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
V4L/DVB: V4L: Events: Add documentation
Add documentation on how to use V4L2 events, both for V4L2 drivers and for V4L2 applications. Signed-off-by: Sakari Ailus <sakari.ailus@maxwell.research.nokia.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
- Loading branch information
Sakari Ailus
authored and
Mauro Carvalho Chehab
committed
May 19, 2010
1 parent
d3d7c96
commit dd96608
Showing
6 changed files
with
331 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| <title>Event Interface</title> | ||
|
|
||
| <para>The V4L2 event interface provides means for 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. | ||
| </para> | ||
|
|
||
| <para>To receive events, the events the user is interested in first must | ||
| be subscribed using the &VIDIOC-SUBSCRIBE-EVENT; ioctl. Once an event is | ||
| subscribed, the events of subscribed types are dequeueable using the | ||
| &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.</para> | ||
|
|
||
| <para>The event subscriptions and event queues are specific to file | ||
| handles. Subscribing an event on one file handle does not affect | ||
| other file handles. | ||
| </para> | ||
|
|
||
| <para>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. </para> | ||
|
|
||
| <!-- | ||
| Local Variables: | ||
| mode: sgml | ||
| sgml-parent-document: "v4l2.sgml" | ||
| indent-tabs-mode: nil | ||
| End: | ||
| --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,124 @@ | ||
| <refentry id="vidioc-dqevent"> | ||
| <refmeta> | ||
| <refentrytitle>ioctl VIDIOC_DQEVENT</refentrytitle> | ||
| &manvol; | ||
| </refmeta> | ||
|
|
||
| <refnamediv> | ||
| <refname>VIDIOC_DQEVENT</refname> | ||
| <refpurpose>Dequeue event</refpurpose> | ||
| </refnamediv> | ||
|
|
||
| <refsynopsisdiv> | ||
| <funcsynopsis> | ||
| <funcprototype> | ||
| <funcdef>int <function>ioctl</function></funcdef> | ||
| <paramdef>int <parameter>fd</parameter></paramdef> | ||
| <paramdef>int <parameter>request</parameter></paramdef> | ||
| <paramdef>struct v4l2_event | ||
| *<parameter>argp</parameter></paramdef> | ||
| </funcprototype> | ||
| </funcsynopsis> | ||
| </refsynopsisdiv> | ||
|
|
||
| <refsect1> | ||
| <title>Arguments</title> | ||
|
|
||
| <variablelist> | ||
| <varlistentry> | ||
| <term><parameter>fd</parameter></term> | ||
| <listitem> | ||
| <para>&fd;</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| <varlistentry> | ||
| <term><parameter>request</parameter></term> | ||
| <listitem> | ||
| <para>VIDIOC_DQEVENT</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| <varlistentry> | ||
| <term><parameter>argp</parameter></term> | ||
| <listitem> | ||
| <para></para> | ||
| </listitem> | ||
| </varlistentry> | ||
| </variablelist> | ||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| <title>Description</title> | ||
|
|
||
| <para>Dequeue an event from a video device. No input is required | ||
| for this ioctl. All the fields of the &v4l2-event; structure are | ||
| filled by the driver. The file handle will also receive exceptions | ||
| which the application may get by e.g. using the select system | ||
| call.</para> | ||
|
|
||
| <table frame="none" pgwide="1" id="v4l2-event"> | ||
| <title>struct <structname>v4l2_event</structname></title> | ||
| <tgroup cols="4"> | ||
| &cs-str; | ||
| <tbody valign="top"> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>type</structfield></entry> | ||
| <entry></entry> | ||
| <entry>Type of the event.</entry> | ||
| </row> | ||
| <row> | ||
| <entry>union</entry> | ||
| <entry><structfield>u</structfield></entry> | ||
| <entry></entry> | ||
| <entry></entry> | ||
| </row> | ||
| <row> | ||
| <entry></entry> | ||
| <entry>__u8</entry> | ||
| <entry><structfield>data</structfield>[64]</entry> | ||
| <entry>Event data. Defined by the event type. The union | ||
| should be used to define easily accessible type for | ||
| events.</entry> | ||
| </row> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>pending</structfield></entry> | ||
| <entry></entry> | ||
| <entry>Number of pending events excluding this one.</entry> | ||
| </row> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>sequence</structfield></entry> | ||
| <entry></entry> | ||
| <entry>Event sequence number. The sequence number is | ||
| incremented for every subscribed event that takes place. | ||
| If sequence numbers are not contiguous it means that | ||
| events have been lost. | ||
| </entry> | ||
| </row> | ||
| <row> | ||
| <entry>struct timeval</entry> | ||
| <entry><structfield>timestamp</structfield></entry> | ||
| <entry></entry> | ||
| <entry>Event timestamp.</entry> | ||
| </row> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>reserved</structfield>[9]</entry> | ||
| <entry></entry> | ||
| <entry>Reserved for future extensions. Drivers must set | ||
| the array to zero.</entry> | ||
| </row> | ||
| </tbody> | ||
| </tgroup> | ||
| </table> | ||
|
|
||
| </refsect1> | ||
| </refentry> | ||
| <!-- | ||
| Local Variables: | ||
| mode: sgml | ||
| sgml-parent-document: "v4l2.sgml" | ||
| indent-tabs-mode: nil | ||
| End: | ||
| --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,104 @@ | ||
| <refentry id="vidioc-subscribe-event"> | ||
| <refmeta> | ||
| <refentrytitle>ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refentrytitle> | ||
| &manvol; | ||
| </refmeta> | ||
|
|
||
| <refnamediv> | ||
| <refname>VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refname> | ||
| <refpurpose>Subscribe or unsubscribe event</refpurpose> | ||
| </refnamediv> | ||
|
|
||
| <refsynopsisdiv> | ||
| <funcsynopsis> | ||
| <funcprototype> | ||
| <funcdef>int <function>ioctl</function></funcdef> | ||
| <paramdef>int <parameter>fd</parameter></paramdef> | ||
| <paramdef>int <parameter>request</parameter></paramdef> | ||
| <paramdef>struct v4l2_event_subscription | ||
| *<parameter>argp</parameter></paramdef> | ||
| </funcprototype> | ||
| </funcsynopsis> | ||
| </refsynopsisdiv> | ||
|
|
||
| <refsect1> | ||
| <title>Arguments</title> | ||
|
|
||
| <variablelist> | ||
| <varlistentry> | ||
| <term><parameter>fd</parameter></term> | ||
| <listitem> | ||
| <para>&fd;</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| <varlistentry> | ||
| <term><parameter>request</parameter></term> | ||
| <listitem> | ||
| <para>VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| <varlistentry> | ||
| <term><parameter>argp</parameter></term> | ||
| <listitem> | ||
| <para></para> | ||
| </listitem> | ||
| </varlistentry> | ||
| </variablelist> | ||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| <title>Description</title> | ||
|
|
||
| <para>Subscribe or unsubscribe V4L2 event. Subscribed events are | ||
| dequeued by using the &VIDIOC-DQEVENT; ioctl.</para> | ||
|
|
||
| <table frame="none" pgwide="1" id="v4l2-event-subscription"> | ||
| <title>struct <structname>v4l2_event_subscription</structname></title> | ||
| <tgroup cols="3"> | ||
| &cs-str; | ||
| <tbody valign="top"> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>type</structfield></entry> | ||
| <entry>Type of the event.</entry> | ||
| </row> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>reserved</structfield>[7]</entry> | ||
| <entry>Reserved for future extensions. Drivers and applications | ||
| must set the array to zero.</entry> | ||
| </row> | ||
| </tbody> | ||
| </tgroup> | ||
| </table> | ||
|
|
||
| <table frame="none" pgwide="1" id="event-type"> | ||
| <title>Event Types</title> | ||
| <tgroup cols="3"> | ||
| &cs-def; | ||
| <tbody valign="top"> | ||
| <row> | ||
| <entry><constant>V4L2_EVENT_ALL</constant></entry> | ||
| <entry>0</entry> | ||
| <entry>All events. V4L2_EVENT_ALL is valid only for | ||
| VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. | ||
| </entry> | ||
| </row> | ||
| <row> | ||
| <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry> | ||
| <entry>0x08000000</entry> | ||
| <entry>Base event number for driver-private events.</entry> | ||
| </row> | ||
| </tbody> | ||
| </tgroup> | ||
| </table> | ||
|
|
||
| </refsect1> | ||
| </refentry> | ||
| <!-- | ||
| Local Variables: | ||
| mode: sgml | ||
| sgml-parent-document: "v4l2.sgml" | ||
| indent-tabs-mode: nil | ||
| End: | ||
| --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters