Add DocBook documentation for media events. Signed-off-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx> --- .../DocBook/media/v4l/media-controller.xml | 1 + .../DocBook/media/v4l/media-ioc-dqevent.xml | 156 +++++++++++++++++++++ 2 files changed, 157 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/media-ioc-dqevent.xml diff --git a/Documentation/DocBook/media/v4l/media-controller.xml b/Documentation/DocBook/media/v4l/media-controller.xml index 2a5a5d0..aa78fcb 100644 --- a/Documentation/DocBook/media/v4l/media-controller.xml +++ b/Documentation/DocBook/media/v4l/media-controller.xml @@ -98,6 +98,7 @@ &sub-media-func-ioctl; <!-- All ioctls go here. --> &sub-media-ioc-device-info; + &sub-media-ioc-dqevent; &sub-media-ioc-g-topology; &sub-media-ioc-enum-entities; &sub-media-ioc-enum-links; diff --git a/Documentation/DocBook/media/v4l/media-ioc-dqevent.xml b/Documentation/DocBook/media/v4l/media-ioc-dqevent.xml new file mode 100644 index 0000000..8cf0462 --- /dev/null +++ b/Documentation/DocBook/media/v4l/media-ioc-dqevent.xml @@ -0,0 +1,156 @@ +<refentry id="media-ioc-dqevent"> + <refmeta> + <refentrytitle>ioctl MEDIA_IOC_DQEVENT</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>MEDIA_IOC_DQEVENT</refname> + <refpurpose>Dequeue a media 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 media_event *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='media-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>MEDIA_IOC_DQEVENT</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>Dequeue a media event from a media device. Both non-blocking + and blocking access is supported. <constant>poll</constant>(2) + IOCTL may be used with poll event type + <constant>POLLPRI</constant> to learn about dequeueable + events.</para> + + <para>Media events are specific to file handle: they are delivered + to and dequeued from each file handle separately.</para> + + <table pgwide="1" frame="none" id="media-event"> + <title>struct <structname>media_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 media event. Set by the driver. See + <xref linkend="media-event-type" /> for available media + event types.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>sequence</structfield></entry> + <entry></entry> + <entry>Event sequence number. The sequence number is file + handle specific and counts from zero until it wraps around + after reaching 32^2-1.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved[4]</structfield></entry> + <entry>Reserved for future extensions. Applications and + drivers must set this to zero.</entry> + </row> + <row> + <entry>union</entry> + <entry><structfield></structfield></entry> + <entry></entry> + <entry>Anonymous union for event type specific data.</entry> + </row> + <row> + <entry></entry> + <entry>struct &media_event_request_complete;</entry> + <entry><structfield>req_complete</structfield></entry> + <entry>Event data for + <constant>MEDIA_EVENT_REQUEST_COMPLETE</constant> event. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="media-event-type"> + <title>Media event types</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>MEDIA_EVENT_REQUEST_COMPLETE</constant></entry> + <entry>1</entry> + <entry>A request has been completed. This media event type + has &media-event-request-complete; associated with it. The +yes + event is only queued to the file handle from which the + event was queued. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="media-event-request-complete"> + <title>struct <structname>media_event_request_complete</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>id</structfield></entry> + <entry>Request ID. The identifier of the request which has + been completed.</entry> + </row> + </tbody> + </tgroup> + </table> + + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>ENOENT</errorcode></term> + <listitem> + <para>No events are available for dequeueing. This is returned + only when non-blocking I/O is used. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> -- 1.9.1 -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
