diff options
Diffstat (limited to 'Documentation/DocBook/v4l')
| -rw-r--r-- | Documentation/DocBook/v4l/common.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/compat.xml | 126 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/controls.xml | 36 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/dev-event.xml | 31 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/io.xml | 21 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/pixfmt.xml | 12 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/v4l2.xml | 5 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/videodev2.h.xml | 10 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-dqevent.xml | 131 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-enuminput.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-g-parm.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-qbuf.xml | 54 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-query-dv-preset.xml | 6 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-querybuf.xml | 7 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-queryctrl.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-reqbufs.xml | 36 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-subscribe-event.xml | 133 |
17 files changed, 500 insertions, 116 deletions
diff --git a/Documentation/DocBook/v4l/common.xml b/Documentation/DocBook/v4l/common.xml index c65f0ac9b6ee..cea23e1c4fc6 100644 --- a/Documentation/DocBook/v4l/common.xml +++ b/Documentation/DocBook/v4l/common.xml @@ -1170,7 +1170,7 @@ frames per second. If less than this number of frames is to be captured or output, applications can request frame skipping or duplicating on the driver side. This is especially useful when using the &func-read; or &func-write;, which are not augmented by timestamps -or sequence counters, and to avoid unneccessary data copying.</para> +or sequence counters, and to avoid unnecessary data copying.</para> <para>Finally these ioctls can be used to determine the number of buffers used internally by a driver in read/write mode. For diff --git a/Documentation/DocBook/v4l/compat.xml b/Documentation/DocBook/v4l/compat.xml index b9dbdf9e6d29..b42b935913cd 100644 --- a/Documentation/DocBook/v4l/compat.xml +++ b/Documentation/DocBook/v4l/compat.xml @@ -2332,15 +2332,26 @@ more information.</para> </listitem> </orderedlist> </section> - </section> + <section> + <title>V4L2 in Linux 2.6.34</title> + <orderedlist> + <listitem> + <para>Added +<constant>V4L2_CID_IRIS_ABSOLUTE</constant> and +<constant>V4L2_CID_IRIS_RELATIVE</constant> controls to the + <link linkend="camera-controls">Camera controls class</link>. + </para> + </listitem> + </orderedlist> + </section> - <section id="other"> - <title>Relation of V4L2 to other Linux multimedia APIs</title> + <section id="other"> + <title>Relation of V4L2 to other Linux multimedia APIs</title> - <section id="xvideo"> - <title>X Video Extension</title> + <section id="xvideo"> + <title>X Video Extension</title> - <para>The X Video Extension (abbreviated XVideo or just Xv) is + <para>The X Video Extension (abbreviated XVideo or just Xv) is an extension of the X Window system, implemented for example by the XFree86 project. Its scope is similar to V4L2, an API to video capture and output devices for X clients. Xv allows applications to display @@ -2351,7 +2362,7 @@ capture or output still images in XPixmaps<footnote> extension available across many operating systems and architectures.</para> - <para>Because the driver is embedded into the X server Xv has a + <para>Because the driver is embedded into the X server Xv has a number of advantages over the V4L2 <link linkend="overlay">video overlay interface</link>. The driver can easily determine the overlay target, &ie; visible graphics memory or off-screen buffers for a @@ -2360,16 +2371,16 @@ overlay, scaling or color-keying, or the clipping functions of the video capture hardware, always in sync with drawing operations or windows moving or changing their stacking order.</para> - <para>To combine the advantages of Xv and V4L a special Xv + <para>To combine the advantages of Xv and V4L a special Xv driver exists in XFree86 and XOrg, just programming any overlay capable Video4Linux device it finds. To enable it <filename>/etc/X11/XF86Config</filename> must contain these lines:</para> - <para><screen> + <para><screen> Section "Module" Load "v4l" EndSection</screen></para> - <para>As of XFree86 4.2 this driver still supports only V4L + <para>As of XFree86 4.2 this driver still supports only V4L ioctls, however it should work just fine with all V4L2 devices through the V4L2 backward-compatibility layer. Since V4L2 permits multiple opens it is possible (if supported by the V4L2 driver) to capture @@ -2377,83 +2388,84 @@ video while an X client requested video overlay. Restrictions of simultaneous capturing and overlay are discussed in <xref linkend="overlay" /> apply.</para> - <para>Only marginally related to V4L2, XFree86 extended Xv to + <para>Only marginally related to V4L2, XFree86 extended Xv to support hardware YUV to RGB conversion and scaling for faster video playback, and added an interface to MPEG-2 decoding hardware. This API is useful to display images captured with V4L2 devices.</para> - </section> + </section> - <section> - <title>Digital Video</title> + <section> + <title>Digital Video</title> - <para>V4L2 does not support digital terrestrial, cable or + <para>V4L2 does not support digital terrestrial, cable or satellite broadcast. A separate project aiming at digital receivers exists. You can find its homepage at <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API has no connection to the V4L2 API except that drivers for hybrid hardware may support both.</para> - </section> + </section> - <section> - <title>Audio Interfaces</title> + <section> + <title>Audio Interfaces</title> - <para>[to do - OSS/ALSA]</para> + <para>[to do - OSS/ALSA]</para> + </section> </section> - </section> - <section id="experimental"> - <title>Experimental API Elements</title> + <section id="experimental"> + <title>Experimental API Elements</title> - <para>The following V4L2 API elements are currently experimental + <para>The following V4L2 API elements are currently experimental and may change in the future.</para> - <itemizedlist> - <listitem> - <para>Video Output Overlay (OSD) Interface, <xref + <itemizedlist> + <listitem> + <para>Video Output Overlay (OSD) Interface, <xref linkend="osd" />.</para> - </listitem> + </listitem> <listitem> - <para><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, + <para><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, &v4l2-buf-type;, <xref linkend="v4l2-buf-type" />.</para> - </listitem> - <listitem> - <para><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant>, + </listitem> + <listitem> + <para><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant>, &VIDIOC-QUERYCAP; ioctl, <xref linkend="device-capabilities" />.</para> - </listitem> - <listitem> - <para>&VIDIOC-ENUM-FRAMESIZES; and + </listitem> + <listitem> + <para>&VIDIOC-ENUM-FRAMESIZES; and &VIDIOC-ENUM-FRAMEINTERVALS; ioctls.</para> - </listitem> - <listitem> - <para>&VIDIOC-G-ENC-INDEX; ioctl.</para> - </listitem> - <listitem> - <para>&VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD; + </listitem> + <listitem> + <para>&VIDIOC-G-ENC-INDEX; ioctl.</para> + </listitem> + <listitem> + <para>&VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD; ioctls.</para> - </listitem> - <listitem> - <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; + </listitem> + <listitem> + <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; ioctls.</para> - </listitem> - <listitem> - <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para> - </listitem> - </itemizedlist> - </section> + </listitem> + <listitem> + <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para> + </listitem> + </itemizedlist> + </section> - <section id="obsolete"> - <title>Obsolete API Elements</title> + <section id="obsolete"> + <title>Obsolete API Elements</title> - <para>The following V4L2 API elements were superseded by new + <para>The following V4L2 API elements were superseded by new interfaces and should not be implemented in new drivers.</para> - <itemizedlist> - <listitem> - <para><constant>VIDIOC_G_MPEGCOMP</constant> and + <itemizedlist> + <listitem> + <para><constant>VIDIOC_G_MPEGCOMP</constant> and <constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls, <xref linkend="extended-controls" />.</para> - </listitem> - </itemizedlist> + </listitem> + </itemizedlist> + </section> </section> <!-- diff --git a/Documentation/DocBook/v4l/controls.xml b/Documentation/DocBook/v4l/controls.xml index f46450610412..8408caaee276 100644 --- a/Documentation/DocBook/v4l/controls.xml +++ b/Documentation/DocBook/v4l/controls.xml @@ -267,6 +267,12 @@ minimum value disables backlight compensation.</entry> <entry>Chroma automatic gain control.</entry> </row> <row> + <entry><constant>V4L2_CID_CHROMA_GAIN</constant></entry> + <entry>integer</entry> + <entry>Adjusts the Chroma gain control (for use when chroma AGC + is disabled).</entry> + </row> + <row> <entry><constant>V4L2_CID_COLOR_KILLER</constant></entry> <entry>boolean</entry> <entry>Enable the color killer (&ie; force a black & white image in case of a weak video signal).</entry> @@ -277,8 +283,15 @@ minimum value disables backlight compensation.</entry> <entry>Selects a color effect. Possible values for <constant>enum v4l2_colorfx</constant> are: <constant>V4L2_COLORFX_NONE</constant> (0), -<constant>V4L2_COLORFX_BW</constant> (1) and -<constant>V4L2_COLORFX_SEPIA</constant> (2).</entry> +<constant>V4L2_COLORFX_BW</constant> (1), +<constant>V4L2_COLORFX_SEPIA</constant> (2), +<constant>V4L2_COLORFX_NEGATIVE</constant> (3), +<constant>V4L2_COLORFX_EMBOSS</constant> (4), +<constant>V4L2_COLORFX_SKETCH</constant> (5), +<constant>V4L2_COLORFX_SKY_BLUE</constant> (6), +<constant>V4L2_COLORFX_GRASS_GREEN</constant> (7), +<constant>V4L2_COLORFX_SKIN_WHITEN</constant> (8) and +<constant>V4L2_COLORFX_VIVID</constant> (9).</entry> </row> <row> <entry><constant>V4L2_CID_ROTATE</constant></entry> @@ -1825,6 +1838,25 @@ wide-angle direction. The zoom speed unit is driver-specific.</entry> <row><entry></entry></row> <row> + <entry spanname="id"><constant>V4L2_CID_IRIS_ABSOLUTE</constant> </entry> + <entry>integer</entry> + </row><row><entry spanname="descr">This control sets the +camera's aperture to the specified value. The unit is undefined. +Larger values open the iris wider, smaller values close it.</entry> + </row> + <row><entry></entry></row> + + <row> + <entry spanname="id"><constant>V4L2_CID_IRIS_RELATIVE</constant> </entry> + <entry>integer</entry> + </row><row><entry spanname="descr">This control modifies the +camera's aperture by the specified amount. The unit is undefined. +Positive values open the iris one step further, negative values close +it one step further. This is a write-only control.</entry> + </row> + <row><entry></entry></row> + + <row> <entry spanname="id"><constant>V4L2_CID_PRIVACY</constant> </entry> <entry>boolean</entry> </row><row><entry spanname="descr">Prevent video from being acquired diff --git a/Documentation/DocBook/v4l/dev-event.xml b/Documentation/DocBook/v4l/dev-event.xml new file mode 100644 index 000000000000..be5a98fb4fab --- /dev/null +++ b/Documentation/DocBook/v4l/dev-event.xml @@ -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: + --> diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml index f92f24323b2a..d424886beda0 100644 --- a/Documentation/DocBook/v4l/io.xml +++ b/Documentation/DocBook/v4l/io.xml @@ -589,7 +589,8 @@ number of a video input as in &v4l2-input; field <entry></entry> <entry>A place holder for future extensions and custom (driver defined) buffer types -<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry> +<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher. Applications +should set this to 0.</entry> </row> </tbody> </tgroup> @@ -701,6 +702,16 @@ They can be both cleared however, then the buffer is in "dequeued" state, in the application domain to say so.</entry> </row> <row> + <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry> + <entry>0x0040</entry> + <entry>When this flag is set, the buffer has been dequeued + successfully, although the data might have been corrupted. + This is recoverable, streaming may continue as normal and + the buffer may be reused normally. + Drivers set this flag when the <constant>VIDIOC_DQBUF</constant> + ioctl is called.</entry> + </row> + <row> <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry> <entry>0x0008</entry> <entry>Drivers set or clear this flag when calling the @@ -917,8 +928,8 @@ order</emphasis>.</para> <para>When the driver provides or accepts images field by field rather than interleaved, it is also important applications understand -how the fields combine to frames. We distinguish between top and -bottom fields, the <emphasis>spatial order</emphasis>: The first line +how the fields combine to frames. We distinguish between top (aka odd) and +bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line of the top field is the first line of an interlaced frame, the first line of the bottom field is the second line of that frame.</para> @@ -971,12 +982,12 @@ between <constant>V4L2_FIELD_TOP</constant> and <row> <entry><constant>V4L2_FIELD_TOP</constant></entry> <entry>2</entry> - <entry>Images consist of the top field only.</entry> + <entry>Images consist of the top (aka odd) field only.</entry> </row> <row> <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> <entry>3</entry> - <entry>Images consist of the bottom field only. + <entry>Images consist of the bottom (aka even) field only. Applications may wish to prevent a device from capturing interlaced images because they will have "comb" or "feathering" artefacts around moving objects.</entry> diff --git a/Documentation/DocBook/v4l/pixfmt.xml b/Documentation/DocBook/v4l/pixfmt.xml index 885968d6a2fc..c4ad0a8e42dc 100644 --- a/Documentation/DocBook/v4l/pixfmt.xml +++ b/Documentation/DocBook/v4l/pixfmt.xml @@ -792,6 +792,18 @@ http://www.thedirks.org/winnov/</ulink></para></entry> <entry>'YYUV'</entry> <entry>unknown</entry> </row> + <row id="V4L2-PIX-FMT-Y4"> + <entry><constant>V4L2_PIX_FMT_Y4</constant></entry> + <entry>'Y04 '</entry> + <entry>Old 4-bit greyscale format. Only the least significant 4 bits of each byte are used, +the other bits are set to 0.</entry> + </row> + <row id="V4L2-PIX-FMT-Y6"> + <entry><constant>V4L2_PIX_FMT_Y6</constant></entry> + <entry>'Y06 '</entry> + <entry>Old 6-bit greyscale format. Only the least significant 6 bits of each byte are used, +the other bits are set to 0.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml index 060105af49e5..7c3c098d5d08 100644 --- a/Documentation/DocBook/v4l/v4l2.xml +++ b/Documentation/DocBook/v4l/v4l2.xml @@ -58,7 +58,7 @@ MPEG stream embedded, sliced VBI data format in this specification. </contrib> <affiliation> <address> - <email>awalls@radix.net</email> + <email>awalls@md.metrocast.net</email> </address> </affiliation> </author> @@ -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/videodev2.h.xml b/Documentation/DocBook/v4l/videodev2.h.xml index 068325940658..865b06d9e679 100644 --- a/Documentation/DocBook/v4l/videodev2.h.xml +++ b/Documentation/DocBook/v4l/videodev2.h.xml @@ -1018,6 +1018,13 @@ enum <link linkend="v4l2-colorfx">v4l2_colorfx</link> { V4L2_COLORFX_NONE = 0, V4L2_COLORFX_BW = 1, V4L2_COLORFX_SEPIA = 2, + V4L2_COLORFX_NEGATIVE = 3, + V4L2_COLORFX_EMBOSS = 4, + V4L2_COLORFX_SKETCH = 5, + V4L2_COLORFX_SKY_BLUE = 6, + V4L2_COLORFX_GRASS_GREEN = 7, + V4L2_COLORFX_SKIN_WHITEN = 8, + V4L2_COLORFX_VIVID = 9. }; #define V4L2_CID_AUTOBRIGHTNESS (V4L2_CID_BASE+32) #define V4L2_CID_BAND_STOP_FILTER (V4L2_CID_BASE+33) @@ -1271,6 +1278,9 @@ enum <link linkend="v4l2-exposure-auto-type">v4l2_exposure_auto_type</link> { #define V4L2_CID_PRIVACY (V4L2_CID_CAMERA_CLASS_BASE+16) +#define V4L2_CID_IRIS_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+17) +#define V4L2_CID_IRIS_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+18) + /* FM Modulator class control IDs */ #define V4L2_CID_FM_TX_CLASS_BASE (V4L2_CTRL_CLASS_FM_TX | 0x900) #define V4L2_CID_FM_TX_CLASS (V4L2_CTRL_CLASS_FM_TX | 1) diff --git a/Documentation/DocBook/v4l/vidioc-dqevent.xml b/Documentation/DocBook/v4l/vidioc-dqevent.xml new file mode 100644 index 000000000000..4e0a7cc30812 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-dqevent.xml @@ -0,0 +1,131 @@ +<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>&v4l2-event-vsync;</entry> + <entry><structfield>vsync</structfield></entry> + <entry>Event data for event V4L2_EVENT_VSYNC. + </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 timespec</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-enuminput.xml b/Documentation/DocBook/v4l/vidioc-enuminput.xml index 71b868e2fb8f..476fe1d2bba0 100644 --- a/Documentation/DocBook/v4l/vidioc-enuminput.xml +++ b/Documentation/DocBook/v4l/vidioc-enuminput.xml @@ -283,7 +283,7 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. <entry>This input supports setting DV presets by using VIDIOC_S_DV_PRESET.</entry> </row> <row> - <entry><constant>V4L2_OUT_CAP_CUSTOM_TIMINGS</constant></entry> + <entry><constant>V4L2_IN_CAP_CUSTOM_TIMINGS</constant></entry> <entry>0x00000002</entry> <entry>This input supports setting custom video timings by using VIDIOC_S_DV_TIMINGS.</entry> </row> diff --git a/Documentation/DocBook/v4l/vidioc-g-parm.xml b/Documentation/DocBook/v4l/vidioc-g-parm.xml index 78332d365ce9..392aa9e5571e 100644 --- a/Documentation/DocBook/v4l/vidioc-g-parm.xml +++ b/Documentation/DocBook/v4l/vidioc-g-parm.xml @@ -55,7 +55,7 @@ captured or output, applications can request frame skipping or duplicating on the driver side. This is especially useful when using the <function>read()</function> or <function>write()</function>, which are not augmented by timestamps or sequence counters, and to avoid -unneccessary data copying.</para> +unnecessary data copying.</para> <para>Further these ioctls can be used to determine the number of buffers used internally by a driver in read/write mode. For diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml index 187081778154..ab691ebf3b93 100644 --- a/Documentation/DocBook/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml @@ -54,12 +54,10 @@ to enqueue an empty (capturing) or filled (output) buffer in the driver's incoming queue. The semantics depend on the selected I/O method.</para> - <para>To enqueue a <link linkend="mmap">memory mapped</link> -buffer applications set the <structfield>type</structfield> field of a -&v4l2-buffer; to the same buffer type as previously &v4l2-format; -<structfield>type</structfield> and &v4l2-requestbuffers; -<structfield>type</structfield>, the <structfield>memory</structfield> -field to <constant>V4L2_MEMORY_MMAP</constant> and the + <para>To enqueue a buffer applications set the <structfield>type</structfield> +field of a &v4l2-buffer; to the same buffer type as was previously used +with &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers; +<structfield>type</structfield>. Applications must also set the <structfield>index</structfield> field. Valid index numbers range from zero to the number of buffers allocated with &VIDIOC-REQBUFS; (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The @@ -70,8 +68,19 @@ intended for output (<structfield>type</structfield> is <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also initialize the <structfield>bytesused</structfield>, <structfield>field</structfield> and -<structfield>timestamp</structfield> fields. See <xref - linkend="buffer" /> for details. When +<structfield>timestamp</structfield> fields, see <xref +linkend="buffer" /> for details. +Applications must also set <structfield>flags</structfield> to 0. If a driver +supports capturing from specific video inputs and you want to specify a video +input, then <structfield>flags</structfield> should be set to +<constant>V4L2_BUF_FLAG_INPUT</constant> and the field +<structfield>input</structfield> must be initialized to the desired input. +The <structfield>reserved</structfield> field must be set to 0. +</para> + + <para>To enqueue a <link linkend="mmap">memory mapped</link> +buffer applications set the <structfield>memory</structfield> +field to <constant>V4L2_MEMORY_MMAP</constant>. When <constant>VIDIOC_QBUF</constant> is called with a pointer to this structure the driver sets the <constant>V4L2_BUF_FLAG_MAPPED</constant> and @@ -81,14 +90,10 @@ structure the driver sets the &EINVAL;.</para> <para>To enqueue a <link linkend="userp">user pointer</link> -buffer applications set the <structfield>type</structfield> field of a -&v4l2-buffer; to the same buffer type as previously &v4l2-format; -<structfield>type</structfield> and &v4l2-requestbuffers; -<structfield>type</structfield>, the <structfield>memory</structfield> -field to <constant>V4L2_MEMORY_USERPTR</constant> and the +buffer applications set the <structfield>memory</structfield> +field to <constant>V4L2_MEMORY_USERPTR</constant>, the <structfield>m.userptr</structfield> field to the address of the -buffer and <structfield>length</structfield> to its size. When the -buffer is intended for output additional fields must be set as above. +buffer and <structfield>length</structfield> to its size. When <constant>VIDIOC_QBUF</constant> is called with a pointer to this structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and @@ -96,16 +101,21 @@ flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and <structfield>flags</structfield> field, or it returns an error code. This ioctl locks the memory pages of the buffer in physical memory, they cannot be swapped out to disk. Buffers remain locked until -dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl are +dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is called, or until the device is closed.</para> <para>Applications call the <constant>VIDIOC_DQBUF</constant> ioctl to dequeue a filled (capturing) or displayed (output) buffer from the driver's outgoing queue. They just set the -<structfield>type</structfield> and <structfield>memory</structfield> +<structfield>type</structfield>, <structfield>memory</structfield> +and <structfield>reserved</structfield> fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant> is called with a pointer to this structure the driver fills the -remaining fields or returns an error code.</para> +remaining fields or returns an error code. The driver may also set +<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield> +field. It indicates a non-critical (recoverable) streaming error. In such case +the application may continue as normal, but should be aware that data in the +dequeued buffer might be corrupted.</para> <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the outgoing queue. When the @@ -152,7 +162,13 @@ enqueue a user pointer buffer.</para> <para><constant>VIDIOC_DQBUF</constant> failed due to an internal error. Can also indicate temporary problems like signal loss. Note the driver might dequeue an (empty) buffer despite -returning an error, or even stop capturing.</para> +returning an error, or even stop capturing. Reusing such buffer may be unsafe +though and its details (e.g. <structfield>index</structfield>) may not be +returned either. It is recommended that drivers indicate recoverable errors +by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead. +In that case the application should be able to safely reuse the buffer and +continue streaming. + </para> </listitem> </varlistentry> </variablelist> diff --git a/Documentation/DocBook/v4l/vidioc-query-dv-preset.xml b/Documentation/DocBook/v4l/vidioc-query-dv-preset.xml index 87e4f0f6151c..402229ee06f6 100644 --- a/Documentation/DocBook/v4l/vidioc-query-dv-preset.xml +++ b/Documentation/DocBook/v4l/vidioc-query-dv-preset.xml @@ -53,8 +53,10 @@ input</refpurpose> automatically, similar to sensing the video standard. To do so, applications call <constant> VIDIOC_QUERY_DV_PRESET</constant> with a pointer to a &v4l2-dv-preset; type. Once the hardware detects a preset, that preset is -returned in the preset field of &v4l2-dv-preset;. When detection is not -possible or fails, the value V4L2_DV_INVALID is returned.</para> +returned in the preset field of &v4l2-dv-preset;. If the preset could not be +detected because there was no signal, or the signal was unreliable, or the +signal did not map to a supported preset, then the value V4L2_DV_INVALID is +returned.</para> </refsect1> <refsect1> diff --git a/Documentation/DocBook/v4l/vidioc-querybuf.xml b/Documentation/DocBook/v4l/vidioc-querybuf.xml index d834993e6191..e649805a4908 100644 --- a/Documentation/DocBook/v4l/vidioc-querybuf.xml +++ b/Documentation/DocBook/v4l/vidioc-querybuf.xml @@ -54,12 +54,13 @@ buffer at any time after buffers have been allocated with the &VIDIOC-REQBUFS; ioctl.</para> <para>Applications set the <structfield>type</structfield> field - of a &v4l2-buffer; to the same buffer type as previously + of a &v4l2-buffer; to the same buffer type as was previously used with &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers; <structfield>type</structfield>, and the <structfield>index</structfield> field. Valid index numbers range from zero to the number of buffers allocated with &VIDIOC-REQBUFS; (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. +The <structfield>reserved</structfield> field should to set to 0. After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to this structure drivers return an error code or fill the rest of the structure.</para> @@ -68,8 +69,8 @@ the structure.</para> <constant>V4L2_BUF_FLAG_MAPPED</constant>, <constant>V4L2_BUF_FLAG_QUEUED</constant> and <constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The -<structfield>memory</structfield> field will be set to -<constant>V4L2_MEMORY_MMAP</constant>, the <structfield>m.offset</structfield> +<structfield>memory</structfield> field will be set to the current +I/O method, the <structfield>m.offset</structfield> contains the offset of the buffer from the start of the device memory, the <structfield>length</structfield> field its size. The driver may or may not set the remaining fields and flags, they are meaningless in diff --git a/Documentation/DocBook/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/v4l/vidioc-queryctrl.xml index 4876ff1a1a04..8e0e055ac934 100644 --- a/Documentation/DocBook/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/v4l/vidioc-queryctrl.xml @@ -325,7 +325,7 @@ should be part of the control documentation.</entry> <entry>n/a</entry> <entry>This is not a control. When <constant>VIDIOC_QUERYCTRL</constant> is called with a control ID -equal to a control class code (see <xref linkend="ctrl-class" />), the +equal to a control class code (see <xref linkend="ctrl-class" />) + 1, the ioctl returns the name of the control class and this control type. Older drivers which do not support this feature return an &EINVAL;.</entry> diff --git a/Documentation/DocBook/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/v4l/vidioc-reqbufs.xml index bab38084454f..69800ae23348 100644 --- a/Documentation/DocBook/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/v4l/vidioc-reqbufs.xml @@ -54,23 +54,23 @@ I/O. Memory mapped buffers are located in device memory and must be allocated with this ioctl before they can be mapped into the application's address space. User buffers are allocated by applications themselves, and this ioctl is merely used to switch the -driver into user pointer I/O mode.</para> +driver into user pointer I/O mode and to setup some internal structures.</para> - <para>To allocate device buffers applications initialize three -fields of a <structname>v4l2_requestbuffers</structname> structure. + <para>To allocate device buffers applications initialize all +fields of the <structname>v4l2_requestbuffers</structname> structure. They set the <structfield>type</structfield> field to the respective stream or buffer type, the <structfield>count</structfield> field to -the desired number of buffers, and <structfield>memory</structfield> -must be set to <constant>V4L2_MEMORY_MMAP</constant>. When the ioctl -is called with a pointer to this structure the driver attempts to -allocate the requested number of buffers and stores the actual number +the desired number of buffers, <structfield>memory</structfield> +must be set to the requested I/O method and the <structfield>reserved</structfield> array +must be zeroed. When the ioctl +is called with a pointer to this structure the driver will attempt to allocate +the requested number of buffers and it stores the actual number allocated in the <structfield>count</structfield> field. It can be smaller than the number requested, even zero, when the driver runs out -of free memory. A larger number is possible when the driver requires -more buffers to function correctly.<footnote> - <para>For example video output requires at least two buffers, +of free memory. A larger number is also possible when the driver requires +more buffers to function correctly. For example video output requires at least two buffers, one displayed and one filled by the application.</para> - </footnote> When memory mapping I/O is not supported the ioctl + <para>When the I/O method is not supported the ioctl returns an &EINVAL;.</para> <para>Applications can call <constant>VIDIOC_REQBUFS</constant> @@ -81,14 +81,6 @@ in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no reason why munmap()ping one or even all buffers must imply streamoff.--></para> - <para>To negotiate user pointer I/O, applications initialize only -the <structfield>type</structfield> field and set -<structfield>memory</structfield> to -<constant>V4L2_MEMORY_USERPTR</constant>. When the ioctl is called -with a pointer to this structure the driver prepares for user pointer -I/O, when this I/O method is not supported the ioctl returns an -&EINVAL;.</para> - <table pgwide="1" frame="none" id="v4l2-requestbuffers"> <title>struct <structname>v4l2_requestbuffers</structname></title> <tgroup cols="3"> @@ -97,9 +89,7 @@ I/O, when this I/O method is not supported the ioctl returns an <row> <entry>__u32</entry> <entry><structfield>count</structfield></entry> - <entry>The number of buffers requested or granted. This -field is only used when <structfield>memory</structfield> is set to -<constant>V4L2_MEMORY_MMAP</constant>.</entry> + <entry>The number of buffers requested or granted.</entry> </row> <row> <entry>&v4l2-buf-type;</entry> @@ -120,7 +110,7 @@ as the &v4l2-format; <structfield>type</structfield> field. See <xref <entry><structfield>reserved</structfield>[2]</entry> <entry>A place holder for future extensions and custom (driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and -higher.</entry> +higher. This array should be zeroed by applications.</entry> </row> </tbody> </tgroup> diff --git a/Documentation/DocBook/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/v4l/vidioc-subscribe-event.xml new file mode 100644 index 000000000000..8b501791aa68 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-subscribe-event.xml @@ -0,0 +1,133 @@ +<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_VSYNC</constant></entry> + <entry>1</entry> + <entry>This event is triggered on the vertical sync. + This event has &v4l2-event-vsync; associated with it. + </entry> + </row> + <row> + <entry><constant>V4L2_EVENT_EOS</constant></entry> + <entry>2</entry> + <entry>This event is triggered when the end of a stream is reached. + This is typically used with MPEG decoders to report to the application + when the last of the MPEG stream has been decoded. + </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> + + <table frame="none" pgwide="1" id="v4l2-event-vsync"> + <title>struct <structname>v4l2_event_vsync</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u8</entry> + <entry><structfield>field</structfield></entry> + <entry>The upcoming field. See &v4l2-field;.</entry> + </row> + </tbody> + </tgroup> + </table> + + </refsect1> +</refentry> +<!-- +Local Variables: +mode: sgml +sgml-parent-document: "v4l2.sgml" +indent-tabs-mode: nil +End: +--> |