diff options
Diffstat (limited to 'Documentation/DocBook')
| -rw-r--r-- | Documentation/DocBook/libata.tmpl | 20 | ||||
| -rw-r--r-- | Documentation/DocBook/media-entities.tmpl | 11 | ||||
| -rw-r--r-- | Documentation/DocBook/sh.tmpl | 10 | ||||
| -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 | 18 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/pixfmt.xml | 12 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/v4l2.xml | 3 | ||||
| -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-qbuf.xml | 14 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-queryctrl.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-reqbufs.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-subscribe-event.xml | 133 | ||||
| -rw-r--r-- | Documentation/DocBook/writing-an-alsa-driver.tmpl | 27 |
17 files changed, 502 insertions, 86 deletions
diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index ff3e5bec1c24..8c5411cfeaf0 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -81,16 +81,14 @@ void (*port_disable) (struct ata_port *); </programlisting> <para> - Called from ata_bus_probe() and ata_bus_reset() error paths, - as well as when unregistering from the SCSI module (rmmod, hot - unplug). + Called from ata_bus_probe() error path, as well as when + unregistering from the SCSI module (rmmod, hot unplug). This function should do whatever needs to be done to take the port out of use. In most cases, ata_port_disable() can be used as this hook. </para> <para> Called from ata_bus_probe() on a failed probe. - Called from ata_bus_reset() on a failed bus reset. Called from ata_scsi_release(). </para> @@ -227,6 +225,18 @@ u8 (*sff_check_altstatus)(struct ata_port *ap); </sect2> + <sect2><title>Write specific ATA shadow register</title> + <programlisting> +void (*sff_set_devctl)(struct ata_port *ap, u8 ctl); + </programlisting> + + <para> + Write the device control ATA shadow register to the hardware. + Most drivers don't need to define this. + </para> + + </sect2> + <sect2><title>Select ATA device on bus</title> <programlisting> void (*sff_dev_select)(struct ata_port *ap, unsigned int device); @@ -477,7 +487,7 @@ void (*host_stop) (struct ata_host_set *host_set); allocates space for a legacy IDE PRD table and returns. </para> <para> - ->port_stop() is called after ->host_stop(). It's sole function + ->port_stop() is called after ->host_stop(). Its sole function is to release DMA/memory resources, now that they are no longer actively being used. Many drivers also free driver-private data from port at this time. diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl index c725cb852c54..5d4d40f429a5 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>"> @@ -83,6 +85,7 @@ <!ENTITY VIDIOC-TRY-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_TRY_ENCODER_CMD</constant></link>"> <!ENTITY VIDIOC-TRY-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_TRY_EXT_CTRLS</constant></link>"> <!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>"> +<!ENTITY VIDIOC-UNSUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_UNSUBSCRIBE_EVENT</constant></link>"> <!-- Types --> <!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>"> @@ -141,6 +144,9 @@ <!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-event-vsync "struct <link linkend='v4l2-event-vsync'>v4l2_event_vsync</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 +206,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 +299,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 +390,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/sh.tmpl b/Documentation/DocBook/sh.tmpl index 0c3dc4c69dd1..d858d92cf6d9 100644 --- a/Documentation/DocBook/sh.tmpl +++ b/Documentation/DocBook/sh.tmpl @@ -19,13 +19,17 @@ </authorgroup> <copyright> - <year>2008</year> + <year>2008-2010</year> <holder>Paul Mundt</holder> </copyright> <copyright> - <year>2008</year> + <year>2008-2010</year> <holder>Renesas Technology Corp.</holder> </copyright> + <copyright> + <year>2010</year> + <holder>Renesas Electronics Corp.</holder> + </copyright> <legalnotice> <para> @@ -77,7 +81,7 @@ </chapter> <chapter id="clk"> <title>Clock Framework Extensions</title> -!Iarch/sh/include/asm/clock.h +!Iinclude/linux/sh_clk.h </chapter> <chapter id="mach"> <title>Machine Specific Interfaces</title> 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 e870330cbf77..d424886beda0 100644 --- a/Documentation/DocBook/v4l/io.xml +++ b/Documentation/DocBook/v4l/io.xml @@ -702,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 @@ -918,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> @@ -972,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..9737243377a3 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/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-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml index b843bd7b3897..ab691ebf3b93 100644 --- a/Documentation/DocBook/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml @@ -111,7 +111,11 @@ from the driver's outgoing queue. They just set the 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 @@ -158,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-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 1c0816372074..69800ae23348 100644 --- a/Documentation/DocBook/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/v4l/vidioc-reqbufs.xml @@ -61,7 +61,7 @@ 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, <structfield>memory</structfield> -must be set to the requested I/O method and the reserved array +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 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: +--> diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl index 0d0f7b4d4b1a..0ba149de2608 100644 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl @@ -5518,34 +5518,41 @@ struct _snd_pcm_runtime { ]]> </programlisting> </informalexample> + + For the raw data, <structfield>size</structfield> field must be + set properly. This specifies the maximum size of the proc file access. </para> <para> - The callback is much more complicated than the text-file - version. You need to use a low-level I/O functions such as + The read/write callbacks of raw mode are more direct than the text mode. + You need to use a low-level I/O functions such as <function>copy_from/to_user()</function> to transfer the data. <informalexample> <programlisting> <![CDATA[ - static long my_file_io_read(struct snd_info_entry *entry, + static ssize_t my_file_io_read(struct snd_info_entry *entry, void *file_private_data, struct file *file, char *buf, - unsigned long count, - unsigned long pos) + size_t count, + loff_t pos) { - long size = count; - if (pos + size > local_max_size) - size = local_max_size - pos; - if (copy_to_user(buf, local_data + pos, size)) + if (copy_to_user(buf, local_data + pos, count)) return -EFAULT; - return size; + return count; } ]]> </programlisting> </informalexample> + + If the size of the info entry has been set up properly, + <structfield>count</structfield> and <structfield>pos</structfield> are + guaranteed to fit within 0 and the given size. + You don't have to check the range in the callbacks unless any + other condition is required. + </para> </chapter> |