[v5,6/6] V4L: Events: Add documentation
Commit Message
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>
---
Documentation/DocBook/media-entities.tmpl | 9 ++
Documentation/DocBook/v4l/dev-event.xml | 34 ++++++
Documentation/DocBook/v4l/v4l2.xml | 3 +
Documentation/DocBook/v4l/vidioc-dqevent.xml | 124 ++++++++++++++++++++
.../DocBook/v4l/vidioc-subscribe-event.xml | 109 +++++++++++++++++
Documentation/video4linux/v4l2-framework.txt | 43 +++++++
6 files changed, 322 insertions(+), 0 deletions(-)
create mode 100644 Documentation/DocBook/v4l/dev-event.xml
create mode 100644 Documentation/DocBook/v4l/vidioc-dqevent.xml
create mode 100644 Documentation/DocBook/v4l/vidioc-subscribe-event.xml
Comments
On Friday 19 February 2010 20:22:00 Sakari Ailus wrote:
> 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>
> ---
> Documentation/DocBook/media-entities.tmpl | 9 ++
> Documentation/DocBook/v4l/dev-event.xml | 34 ++++++
> Documentation/DocBook/v4l/v4l2.xml | 3 +
> Documentation/DocBook/v4l/vidioc-dqevent.xml | 124 ++++++++++++++++++++
> .../DocBook/v4l/vidioc-subscribe-event.xml | 109 +++++++++++++++++
> Documentation/video4linux/v4l2-framework.txt | 43 +++++++
> 6 files changed, 322 insertions(+), 0 deletions(-)
> create mode 100644 Documentation/DocBook/v4l/dev-event.xml
> create mode 100644 Documentation/DocBook/v4l/vidioc-dqevent.xml
> create mode 100644 Documentation/DocBook/v4l/vidioc-subscribe-event.xml
>
> diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl
> index c725cb8..770be3c 100644
> --- a/Documentation/DocBook/media-entities.tmpl
> +++ b/Documentation/DocBook/media-entities.tmpl
> @@ -17,6 +17,7 @@
> <!ENTITY VIDIOC-DBG-G-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_G_REGISTER</constant></link>">
> <!ENTITY VIDIOC-DBG-S-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_S_REGISTER</constant></link>">
> <!ENTITY VIDIOC-DQBUF "<link linkend='vidioc-qbuf'><constant>VIDIOC_DQBUF</constant></link>">
> +<!ENTITY VIDIOC-DQEVENT "<link linkend='vidioc-dqevent'><constant>VIDIOC_DQEVENT</constant></link>">
> <!ENTITY VIDIOC-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_ENCODER_CMD</constant></link>">
> <!ENTITY VIDIOC-ENUMAUDIO "<link linkend='vidioc-enumaudio'><constant>VIDIOC_ENUMAUDIO</constant></link>">
> <!ENTITY VIDIOC-ENUMAUDOUT "<link linkend='vidioc-enumaudioout'><constant>VIDIOC_ENUMAUDOUT</constant></link>">
> @@ -60,6 +61,7 @@
> <!ENTITY VIDIOC-REQBUFS "<link linkend='vidioc-reqbufs'><constant>VIDIOC_REQBUFS</constant></link>">
> <!ENTITY VIDIOC-STREAMOFF "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMOFF</constant></link>">
> <!ENTITY VIDIOC-STREAMON "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMON</constant></link>">
> +<!ENTITY VIDIOC-SUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_SUBSCRIBE_EVENT</constant></link>">
> <!ENTITY VIDIOC-S-AUDIO "<link linkend='vidioc-g-audio'><constant>VIDIOC_S_AUDIO</constant></link>">
> <!ENTITY VIDIOC-S-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_S_AUDOUT</constant></link>">
> <!ENTITY VIDIOC-S-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_S_CROP</constant></link>">
> @@ -141,6 +143,8 @@
> <!ENTITY v4l2-enc-idx "struct <link linkend='v4l2-enc-idx'>v4l2_enc_idx</link>">
> <!ENTITY v4l2-enc-idx-entry "struct <link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link>">
> <!ENTITY v4l2-encoder-cmd "struct <link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link>">
> +<!ENTITY v4l2-event "struct <link linkend='v4l2-event'>v4l2_event</link>">
> +<!ENTITY v4l2-event-subscription "struct <link linkend='v4l2-event-subscription'>v4l2_event_subscription</link>">
> <!ENTITY v4l2-ext-control "struct <link linkend='v4l2-ext-control'>v4l2_ext_control</link>">
> <!ENTITY v4l2-ext-controls "struct <link linkend='v4l2-ext-controls'>v4l2_ext_controls</link>">
> <!ENTITY v4l2-fmtdesc "struct <link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link>">
> @@ -200,6 +204,7 @@
> <!ENTITY sub-controls SYSTEM "v4l/controls.xml">
> <!ENTITY sub-dev-capture SYSTEM "v4l/dev-capture.xml">
> <!ENTITY sub-dev-codec SYSTEM "v4l/dev-codec.xml">
> +<!ENTITY sub-dev-event SYSTEM "v4l/dev-event.xml">
> <!ENTITY sub-dev-effect SYSTEM "v4l/dev-effect.xml">
> <!ENTITY sub-dev-osd SYSTEM "v4l/dev-osd.xml">
> <!ENTITY sub-dev-output SYSTEM "v4l/dev-output.xml">
> @@ -292,6 +297,8 @@
> <!ENTITY sub-v4l2grab-c SYSTEM "v4l/v4l2grab.c.xml">
> <!ENTITY sub-videodev2-h SYSTEM "v4l/videodev2.h.xml">
> <!ENTITY sub-v4l2 SYSTEM "v4l/v4l2.xml">
> +<!ENTITY sub-dqevent SYSTEM "v4l/vidioc-dqevent.xml">
> +<!ENTITY sub-subscribe-event SYSTEM "v4l/vidioc-subscribe-event.xml">
> <!ENTITY sub-intro SYSTEM "dvb/intro.xml">
> <!ENTITY sub-frontend SYSTEM "dvb/frontend.xml">
> <!ENTITY sub-dvbproperty SYSTEM "dvb/dvbproperty.xml">
> @@ -381,3 +388,5 @@
> <!ENTITY reqbufs SYSTEM "v4l/vidioc-reqbufs.xml">
> <!ENTITY s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml">
> <!ENTITY streamon SYSTEM "v4l/vidioc-streamon.xml">
> +<!ENTITY dqevent SYSTEM "v4l/vidioc-dqevent.xml">
> +<!ENTITY subscribe_event SYSTEM "v4l/vidioc-subscribe-event.xml">
> diff --git a/Documentation/DocBook/v4l/dev-event.xml b/Documentation/DocBook/v4l/dev-event.xml
> new file mode 100644
> index 0000000..70a9895
> --- /dev/null
> +++ b/Documentation/DocBook/v4l/dev-event.xml
> @@ -0,0 +1,34 @@
> + <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 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 subscribe or 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 are 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:
> + -->
> diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml
> index 060105a..9737243 100644
> --- a/Documentation/DocBook/v4l/v4l2.xml
> +++ b/Documentation/DocBook/v4l/v4l2.xml
> @@ -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;
> diff --git a/Documentation/DocBook/v4l/vidioc-dqevent.xml b/Documentation/DocBook/v4l/vidioc-dqevent.xml
> new file mode 100644
> index 0000000..eb45c16
> --- /dev/null
> +++ b/Documentation/DocBook/v4l/vidioc-dqevent.xml
> @@ -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:
> +-->
> diff --git a/Documentation/DocBook/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/v4l/vidioc-subscribe-event.xml
> new file mode 100644
> index 0000000..943de5c
> --- /dev/null
> +++ b/Documentation/DocBook/v4l/vidioc-subscribe-event.xml
> @@ -0,0 +1,109 @@
> +<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-SUBSCRIBE-EVENT; ioctl.</para>
You mean VIDIOC-DQUEUE, I assume.
> +
> + There are standard and private events. New standard events must
> + use the smallest available event type.
That last sentence belongs in v4l2-framework.txt, not here.
> +
> + <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 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. The user may subscribe
> + for all events supported by the driver by subscribing a
> + special event, V4L2_EVENT_ALL.</entry>
> + </row>
> + <row>
> + <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
> + <entry>0x08000000</entry> <entry>Private events start from
> + this number. The drivers must allocate their events
> + starting from base (V4L2_EVENT_PRIVATE_START + n * 1024)
> + where individual events start from base + 1.</entry>
Again, that last sentence belongs in v4l2-framework.txt.
> + </row>
> + </tbody>
> + </tgroup>
> + </table>
> +
> + </refsect1>
> +</refentry>
> +<!--
> +Local Variables:
> +mode: sgml
> +sgml-parent-document: "v4l2.sgml"
> +indent-tabs-mode: nil
> +End:
> +-->
> diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
> index 08f9e59..7494a64 100644
> --- a/Documentation/video4linux/v4l2-framework.txt
> +++ b/Documentation/video4linux/v4l2-framework.txt
> @@ -731,3 +731,46 @@ Useful functions:
> The users of v4l2_fh know whether a driver uses v4l2_fh as its
> file.private_data pointer by testing the V4L2_FL_USES_V4L2_FH bit in
> video_device.flags.
> +
> +V4L2 events
> +-----------
> +
> +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. To
> +support V4L2 events, the driver must
Must what?
> +
> +- v4l2_event_alloc()
> +
> + 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 has been allocated. The function may not be called in
> + atomic context. If the driver only wants to initialise events it is fine
> + to call v4l2_event_alloc() with 0 allocation. This allows passing the
> + ioctls to the driver.
This is unnecessarily complex. And based on my comments on the previous patches
it is also not needed. Drivers can call v4l2_event_alloc either after calling
v4l2_fh_init or in the subscribe_event op.
> +
> +- v4l2_event_queue()
> +
> + Queue events to video device. The driver's only responsibility is to fill
> + in the type and the data fields. The other fields will be filled in by
> + V4L2.
> +
> +- Define vidioc_subscribe_event in struct v4l2_ioctl_ops. The
> + vidioc_subscribe_event must chech the driver is able to produce events
typo: check
> + with specified event id. Then it calls v4l2_event_subscribe() to subscribe
> + the event.
> +
> +- Define vidioc_unsubscribe_event in struct v4l2_ioctl_ops. A driver may use
> + v4l2_event_unsubscribe directly unless it wants to be involved in
> + unsubscription process.
> +
> +- To support V4L2_EVENTS_ALL, the driver must handle the special id
> + V4L2_EVENTS_ALL when subscribing for events. The function
> + v4l2_event_subscribe_many() is useful in implementing this. Unsubscription
> + of all events is already handled by vidioc_unsubscribe_event().
This should only be supported by unsubscribe.
> +
> +- Events are delivered to user space through the poll system call. The
> + driver should use a separate wait queue for the V4L2 events.
I don't quite get what you mean by this. I am also missing a reference to the
fh->events->wait queue. That's a rather important piece of information to
document.
You should also document v4l2_event_pending and mention that dequeuing is
done internally through the v4l2_event_dequeue call that needs no driver
support.
Regards,
Hans
> +
> +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.
>
@@ -17,6 +17,7 @@
<!ENTITY VIDIOC-DBG-G-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_G_REGISTER</constant></link>">
<!ENTITY VIDIOC-DBG-S-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_S_REGISTER</constant></link>">
<!ENTITY VIDIOC-DQBUF "<link linkend='vidioc-qbuf'><constant>VIDIOC_DQBUF</constant></link>">
+<!ENTITY VIDIOC-DQEVENT "<link linkend='vidioc-dqevent'><constant>VIDIOC_DQEVENT</constant></link>">
<!ENTITY VIDIOC-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_ENCODER_CMD</constant></link>">
<!ENTITY VIDIOC-ENUMAUDIO "<link linkend='vidioc-enumaudio'><constant>VIDIOC_ENUMAUDIO</constant></link>">
<!ENTITY VIDIOC-ENUMAUDOUT "<link linkend='vidioc-enumaudioout'><constant>VIDIOC_ENUMAUDOUT</constant></link>">
@@ -60,6 +61,7 @@
<!ENTITY VIDIOC-REQBUFS "<link linkend='vidioc-reqbufs'><constant>VIDIOC_REQBUFS</constant></link>">
<!ENTITY VIDIOC-STREAMOFF "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMOFF</constant></link>">
<!ENTITY VIDIOC-STREAMON "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMON</constant></link>">
+<!ENTITY VIDIOC-SUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_SUBSCRIBE_EVENT</constant></link>">
<!ENTITY VIDIOC-S-AUDIO "<link linkend='vidioc-g-audio'><constant>VIDIOC_S_AUDIO</constant></link>">
<!ENTITY VIDIOC-S-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_S_AUDOUT</constant></link>">
<!ENTITY VIDIOC-S-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_S_CROP</constant></link>">
@@ -141,6 +143,8 @@
<!ENTITY v4l2-enc-idx "struct <link linkend='v4l2-enc-idx'>v4l2_enc_idx</link>">
<!ENTITY v4l2-enc-idx-entry "struct <link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link>">
<!ENTITY v4l2-encoder-cmd "struct <link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link>">
+<!ENTITY v4l2-event "struct <link linkend='v4l2-event'>v4l2_event</link>">
+<!ENTITY v4l2-event-subscription "struct <link linkend='v4l2-event-subscription'>v4l2_event_subscription</link>">
<!ENTITY v4l2-ext-control "struct <link linkend='v4l2-ext-control'>v4l2_ext_control</link>">
<!ENTITY v4l2-ext-controls "struct <link linkend='v4l2-ext-controls'>v4l2_ext_controls</link>">
<!ENTITY v4l2-fmtdesc "struct <link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link>">
@@ -200,6 +204,7 @@
<!ENTITY sub-controls SYSTEM "v4l/controls.xml">
<!ENTITY sub-dev-capture SYSTEM "v4l/dev-capture.xml">
<!ENTITY sub-dev-codec SYSTEM "v4l/dev-codec.xml">
+<!ENTITY sub-dev-event SYSTEM "v4l/dev-event.xml">
<!ENTITY sub-dev-effect SYSTEM "v4l/dev-effect.xml">
<!ENTITY sub-dev-osd SYSTEM "v4l/dev-osd.xml">
<!ENTITY sub-dev-output SYSTEM "v4l/dev-output.xml">
@@ -292,6 +297,8 @@
<!ENTITY sub-v4l2grab-c SYSTEM "v4l/v4l2grab.c.xml">
<!ENTITY sub-videodev2-h SYSTEM "v4l/videodev2.h.xml">
<!ENTITY sub-v4l2 SYSTEM "v4l/v4l2.xml">
+<!ENTITY sub-dqevent SYSTEM "v4l/vidioc-dqevent.xml">
+<!ENTITY sub-subscribe-event SYSTEM "v4l/vidioc-subscribe-event.xml">
<!ENTITY sub-intro SYSTEM "dvb/intro.xml">
<!ENTITY sub-frontend SYSTEM "dvb/frontend.xml">
<!ENTITY sub-dvbproperty SYSTEM "dvb/dvbproperty.xml">
@@ -381,3 +388,5 @@
<!ENTITY reqbufs SYSTEM "v4l/vidioc-reqbufs.xml">
<!ENTITY s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml">
<!ENTITY streamon SYSTEM "v4l/vidioc-streamon.xml">
+<!ENTITY dqevent SYSTEM "v4l/vidioc-dqevent.xml">
+<!ENTITY subscribe_event SYSTEM "v4l/vidioc-subscribe-event.xml">
new file mode 100644
@@ -0,0 +1,34 @@
+ <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 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 subscribe or 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 are 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;
new file mode 100644
@@ -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:
+-->
new file mode 100644
@@ -0,0 +1,109 @@
+<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-SUBSCRIBE-EVENT; ioctl.</para>
+
+ There are standard and private events. New standard events must
+ use the smallest available event type.
+
+ <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 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. The user may subscribe
+ for all events supported by the driver by subscribing a
+ special event, V4L2_EVENT_ALL.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
+ <entry>0x08000000</entry> <entry>Private events start from
+ this number. The drivers must allocate their events
+ starting from base (V4L2_EVENT_PRIVATE_START + n * 1024)
+ where individual events start from base + 1.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </refsect1>
+</refentry>
+<!--
+Local Variables:
+mode: sgml
+sgml-parent-document: "v4l2.sgml"
+indent-tabs-mode: nil
+End:
+-->
@@ -731,3 +731,46 @@ Useful functions:
The users of v4l2_fh know whether a driver uses v4l2_fh as its
file.private_data pointer by testing the V4L2_FL_USES_V4L2_FH bit in
video_device.flags.
+
+V4L2 events
+-----------
+
+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. To
+support V4L2 events, the driver must
+
+- v4l2_event_alloc()
+
+ 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 has been allocated. The function may not be called in
+ atomic context. If the driver only wants to initialise events it is fine
+ to call v4l2_event_alloc() with 0 allocation. This allows passing the
+ ioctls to the driver.
+
+- v4l2_event_queue()
+
+ Queue events to video device. The driver's only responsibility is to fill
+ in the type and the data fields. The other fields will be filled in by
+ V4L2.
+
+- Define vidioc_subscribe_event in struct v4l2_ioctl_ops. The
+ vidioc_subscribe_event must chech the driver is able to produce events
+ with specified event id. Then it calls v4l2_event_subscribe() to subscribe
+ the event.
+
+- Define vidioc_unsubscribe_event in struct v4l2_ioctl_ops. A driver may use
+ v4l2_event_unsubscribe directly unless it wants to be involved in
+ unsubscription process.
+
+- To support V4L2_EVENTS_ALL, the driver must handle the special id
+ V4L2_EVENTS_ALL when subscribing for events. The function
+ v4l2_event_subscribe_many() is useful in implementing this. Unsubscription
+ of all events is already handled by vidioc_unsubscribe_event().
+
+- Events are delivered to user space through the poll system call. The
+ driver should use a separate wait queue for the V4L2 events.
+
+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.