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>
This commit is contained in:
Sakari Ailus
committed by
Mauro Carvalho Chehab
Mauro Carvalho Chehab
parent
d3d7c96356
commit
dd96608369
31
Documentation/DocBook/v4l/dev-event.xml
Normal file
31
Documentation/DocBook/v4l/dev-event.xml
Normal file
@ -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:
|
||||
-->
|
||||
@ -401,6 +401,7 @@ and discussions on the V4L mailing list.</revremark>
|
||||
<section id="ttx"> &sub-dev-teletext; </section>
|
||||
<section id="radio"> &sub-dev-radio; </section>
|
||||
<section id="rds"> &sub-dev-rds; </section>
|
||||
<section id="event"> &sub-dev-event; </section>
|
||||
</chapter>
|
||||
|
||||
<chapter id="driver">
|
||||
@ -426,6 +427,7 @@ and discussions on the V4L mailing list.</revremark>
|
||||
&sub-cropcap;
|
||||
&sub-dbg-g-chip-ident;
|
||||
&sub-dbg-g-register;
|
||||
&sub-dqevent;
|
||||
&sub-encoder-cmd;
|
||||
&sub-enumaudio;
|
||||
&sub-enumaudioout;
|
||||
@ -467,6 +469,7 @@ and discussions on the V4L mailing list.</revremark>
|
||||
&sub-reqbufs;
|
||||
&sub-s-hw-freq-seek;
|
||||
&sub-streamon;
|
||||
&sub-subscribe-event;
|
||||
<!-- End of ioctls. -->
|
||||
&sub-mmap;
|
||||
&sub-munmap;
|
||||
|
||||
124
Documentation/DocBook/v4l/vidioc-dqevent.xml
Normal file
124
Documentation/DocBook/v4l/vidioc-dqevent.xml
Normal file
@ -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:
|
||||
-->
|
||||
104
Documentation/DocBook/v4l/vidioc-subscribe-event.xml
Normal file
104
Documentation/DocBook/v4l/vidioc-subscribe-event.xml
Normal file
@ -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:
|
||||
-->
|
||||
Reference in New Issue
Block a user