diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l')
| -rw-r--r-- | Documentation/DocBook/media/v4l/compat.xml | 11 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/controls.xml | 43 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/dev-subdev.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/io.xml | 27 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/v4l2.xml | 11 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-create-bufs.xml | 139 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-dqevent.xml | 129 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml | 88 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-queryctrl.xml | 9 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml | 123 |
10 files changed, 452 insertions, 130 deletions
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index ce1004a7da5..b68698f96e7 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2370,6 +2370,14 @@ that used it. It was originally scheduled for removal in 2.6.35. </listitem> </orderedlist> </section> + <section> + <title>V4L2 in Linux 3.2</title> + <orderedlist> + <listitem> + <para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.</para> + </listitem> + </orderedlist> + </section> <section id="other"> <title>Relation of V4L2 to other Linux multimedia APIs</title> @@ -2478,6 +2486,9 @@ ioctls.</para> <listitem> <para>Flash API. <xref linkend="flash-controls" /></para> </listitem> + <listitem> + <para>&VIDIOC-CREATE-BUFS; and &VIDIOC-PREPARE-BUF; ioctls.</para> + </listitem> </itemizedlist> </section> diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 85164016ed2..3bc5ee8b2c7 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -232,8 +232,9 @@ control is deprecated. New drivers and applications should use the <entry>Enables a power line frequency filter to avoid flicker. Possible values for <constant>enum v4l2_power_line_frequency</constant> are: <constant>V4L2_CID_POWER_LINE_FREQUENCY_DISABLED</constant> (0), -<constant>V4L2_CID_POWER_LINE_FREQUENCY_50HZ</constant> (1) and -<constant>V4L2_CID_POWER_LINE_FREQUENCY_60HZ</constant> (2).</entry> +<constant>V4L2_CID_POWER_LINE_FREQUENCY_50HZ</constant> (1), +<constant>V4L2_CID_POWER_LINE_FREQUENCY_60HZ</constant> (2) and +<constant>V4L2_CID_POWER_LINE_FREQUENCY_AUTO</constant> (3).</entry> </row> <row> <entry><constant>V4L2_CID_HUE_AUTO</constant></entry> @@ -1455,7 +1456,7 @@ Applicable to the H264 encoder.</entry> </row> <row><entry></entry></row> - <row> + <row id="v4l2-mpeg-video-h264-vui-sar-idc"> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC</constant> </entry> <entry>enum v4l2_mpeg_video_h264_vui_sar_idc</entry> </row> @@ -1561,7 +1562,7 @@ Applicable to the H264 encoder.</entry> </row> <row><entry></entry></row> - <row> + <row id="v4l2-mpeg-video-h264-level"> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LEVEL</constant> </entry> <entry>enum v4l2_mpeg_video_h264_level</entry> </row> @@ -1641,7 +1642,7 @@ Possible values are:</entry> </row> <row><entry></entry></row> - <row> + <row id="v4l2-mpeg-video-mpeg4-level"> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL</constant> </entry> <entry>enum v4l2_mpeg_video_mpeg4_level</entry> </row> @@ -1689,9 +1690,9 @@ Possible values are:</entry> </row> <row><entry></entry></row> - <row> + <row id="v4l2-mpeg-video-h264-profile"> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_PROFILE</constant> </entry> - <entry>enum v4l2_mpeg_h264_profile</entry> + <entry>enum v4l2_mpeg_video_h264_profile</entry> </row> <row><entry spanname="descr">The profile information for H264. Applicable to the H264 encoder. @@ -1774,9 +1775,9 @@ Possible values are:</entry> </row> <row><entry></entry></row> - <row> + <row id="v4l2-mpeg-video-mpeg4-profile"> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE</constant> </entry> - <entry>enum v4l2_mpeg_mpeg4_profile</entry> + <entry>enum v4l2_mpeg_video_mpeg4_profile</entry> </row> <row><entry spanname="descr">The profile information for MPEG4. Applicable to the MPEG4 encoder. @@ -1820,9 +1821,9 @@ Applicable to the encoder. </row> <row><entry></entry></row> - <row> + <row id="v4l2-mpeg-video-multi-slice-mode"> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> </entry> - <entry>enum v4l2_mpeg_multi_slice_mode</entry> + <entry>enum v4l2_mpeg_video_multi_slice_mode</entry> </row> <row><entry spanname="descr">Determines how the encoder should handle division of frame into slices. Applicable to the encoder. @@ -1868,9 +1869,9 @@ Applicable to the encoder.</entry> </row> <row><entry></entry></row> - <row> + <row id="v4l2-mpeg-video-h264-loop-filter-mode"> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE</constant> </entry> - <entry>enum v4l2_mpeg_h264_loop_filter_mode</entry> + <entry>enum v4l2_mpeg_video_h264_loop_filter_mode</entry> </row> <row><entry spanname="descr">Loop filter mode for H264 encoder. Possible values are:</entry> @@ -1913,9 +1914,9 @@ Applicable to the H264 encoder.</entry> </row> <row><entry></entry></row> - <row> + <row id="v4l2-mpeg-video-h264-entropy-mode"> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE</constant> </entry> - <entry>enum v4l2_mpeg_h264_symbol_mode</entry> + <entry>enum v4l2_mpeg_video_h264_entropy_mode</entry> </row> <row><entry spanname="descr">Entropy coding mode for H264 - CABAC/CAVALC. Applicable to the H264 encoder. @@ -2140,9 +2141,9 @@ previous frames. Applicable to the H264 encoder.</entry> </row> <row><entry></entry></row> - <row> + <row id="v4l2-mpeg-video-header-mode"> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_HEADER_MODE</constant> </entry> - <entry>enum v4l2_mpeg_header_mode</entry> + <entry>enum v4l2_mpeg_video_header_mode</entry> </row> <row><entry spanname="descr">Determines whether the header is returned as the first buffer or is it returned together with the first frame. Applicable to encoders. @@ -2320,9 +2321,9 @@ Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPE Applicable to the H264 encoder.</entry> </row> <row><entry></entry></row> - <row> + <row id="v4l2-mpeg-mfc51-video-frame-skip-mode"> <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE</constant> </entry> - <entry>enum v4l2_mpeg_mfc51_frame_skip_mode</entry> + <entry>enum v4l2_mpeg_mfc51_video_frame_skip_mode</entry> </row> <row><entry spanname="descr"> Indicates in what conditions the encoder should skip frames. If encoding a frame would cause the encoded stream to be larger then @@ -2361,9 +2362,9 @@ the stream will meet tight bandwidth contraints. Applicable to encoders. </entry> </row> <row><entry></entry></row> - <row> + <row id="v4l2-mpeg-mfc51-video-force-frame-type"> <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE</constant> </entry> - <entry>enum v4l2_mpeg_mfc51_force_frame_type</entry> + <entry>enum v4l2_mpeg_mfc51_video_force_frame_type</entry> </row> <row><entry spanname="descr">Force a frame type for the next queued buffer. Applicable to encoders. Possible values are:</entry> diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index 05c8fefcbcb..0916a7343a1 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -266,7 +266,7 @@ <para>When satisfied with the try results, applications can set the active formats by setting the <structfield>which</structfield> argument to - <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. Active formats are changed + <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. Active formats are changed exactly as try formats by drivers. To avoid modifying the hardware state during format negotiation, applications should negotiate try formats first and then modify the active settings using the try formats returned during diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index c57d1ec6291..3f47df1aa54 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -927,6 +927,33 @@ ioctl is called.</entry> Applications set or clear this flag before calling the <constant>VIDIOC_QBUF</constant> ioctl.</entry> </row> + <row> + <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry> + <entry>0x0400</entry> + <entry>The buffer has been prepared for I/O and can be queued by the +application. Drivers set or clear this flag when the +<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link + linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link + linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link + linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry> + </row> + <row> + <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry> + <entry>0x0400</entry> + <entry>Caches do not have to be invalidated for this buffer. +Typically applications shall use this flag if the data captured in the buffer +is not going to be touched by the CPU, instead the buffer will, probably, be +passed on to a DMA-capable hardware unit for further processing or output. +</entry> + </row> + <row> + <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry> + <entry>0x0800</entry> + <entry>Caches do not have to be cleaned for this buffer. +Typically applications shall use this flag for output buffers if the data +in this buffer has not been created by the CPU but by some DMA-capable unit, +in which case caches have not been used.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 0d05e8747c1..2ab365c10fb 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -128,6 +128,13 @@ structs, ioctls) must be noted in more detail in the history chapter applications. --> <revision> + <revnumber>3.2</revnumber> + <date>2011-08-26</date> + <authorinitials>hv</authorinitials> + <revremark>Added V4L2_CTRL_FLAG_VOLATILE.</revremark> + </revision> + + <revision> <revnumber>3.1</revnumber> <date>2011-06-27</date> <authorinitials>mcc, po, hv</authorinitials> @@ -410,7 +417,7 @@ and discussions on the V4L mailing list.</revremark> </partinfo> <title>Video for Linux Two API Specification</title> - <subtitle>Revision 3.1</subtitle> + <subtitle>Revision 3.2</subtitle> <chapter id="common"> &sub-common; @@ -462,6 +469,7 @@ and discussions on the V4L mailing list.</revremark> &sub-close; &sub-ioctl; <!-- All ioctls go here. --> + &sub-create-bufs; &sub-cropcap; &sub-dbg-g-chip-ident; &sub-dbg-g-register; @@ -504,6 +512,7 @@ and discussions on the V4L mailing list.</revremark> &sub-queryctrl; &sub-query-dv-preset; &sub-querystd; + &sub-prepare-buf; &sub-reqbufs; &sub-s-hw-freq-seek; &sub-streamon; diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml new file mode 100644 index 00000000000..73ae8a6cd00 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -0,0 +1,139 @@ +<refentry id="vidioc-create-bufs"> + <refmeta> + <refentrytitle>ioctl VIDIOC_CREATE_BUFS</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_CREATE_BUFS</refname> + <refpurpose>Create buffers for Memory Mapped or User Pointer I/O</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_create_buffers *<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_CREATE_BUFS</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>This ioctl is used to create buffers for <link linkend="mmap">memory +mapped</link> or <link linkend="userp">user pointer</link> +I/O. It can be used as an alternative or in addition to the +<constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter control over buffers +is required. This ioctl can be called multiple times to create buffers of +different sizes.</para> + + <para>To allocate device buffers applications initialize relevant fields of +the <structname>v4l2_create_buffers</structname> structure. They set the +<structfield>type</structfield> field in the +<structname>v4l2_format</structname> structure, embedded in this +structure, to the respective stream or buffer type. +<structfield>count</structfield> must be set to the number of required buffers. +<structfield>memory</structfield> specifies the required I/O method. The +<structfield>format</structfield> field shall typically be filled in using +either the <constant>VIDIOC_TRY_FMT</constant> or +<constant>VIDIOC_G_FMT</constant> ioctl(). Additionally, applications can adjust +<structfield>sizeimage</structfield> fields to fit their specific needs. The +<structfield>reserved</structfield> array must be zeroed.</para> + + <para>When the ioctl is called with a pointer to this structure the driver +will attempt to allocate up to the requested number of buffers and store the +actual number allocated and the starting index in the +<structfield>count</structfield> and the <structfield>index</structfield> fields +respectively. On return <structfield>count</structfield> can be smaller than +the number requested. The driver may also increase buffer sizes if required, +however, it will not update <structfield>sizeimage</structfield> field values. +The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that +information.</para> + + <table pgwide="1" frame="none" id="v4l2-create-buffers"> + <title>struct <structname>v4l2_create_buffers</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>index</structfield></entry> + <entry>The starting buffer index, returned by the driver.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>count</structfield></entry> + <entry>The number of buffers requested or granted.</entry> + </row> + <row> + <entry>&v4l2-memory;</entry> + <entry><structfield>memory</structfield></entry> + <entry>Applications set this field to +<constant>V4L2_MEMORY_MMAP</constant> or +<constant>V4L2_MEMORY_USERPTR</constant>.</entry> + </row> + <row> + <entry>&v4l2-format;</entry> + <entry><structfield>format</structfield></entry> + <entry>Filled in by the application, preserved by the driver.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[8]</entry> + <entry>A place holder for future extensions.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>ENOMEM</errorcode></term> + <listitem> + <para>No memory to allocate buffers for <link linkend="mmap">memory +mapped</link> I/O.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The buffer type (<structfield>type</structfield> field) or the +requested I/O method (<structfield>memory</structfield>) is not +supported.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml index 7769642ee43..e8714aa1643 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml @@ -88,6 +88,12 @@ </row> <row> <entry></entry> + <entry>&v4l2-event-frame-sync;</entry> + <entry><structfield>frame</structfield></entry> + <entry>Event data for event V4L2_EVENT_FRAME_SYNC.</entry> + </row> + <row> + <entry></entry> <entry>__u8</entry> <entry><structfield>data</structfield>[64]</entry> <entry>Event data. Defined by the event type. The union @@ -135,6 +141,129 @@ </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> + + <table frame="none" pgwide="1" id="v4l2-event-ctrl"> + <title>struct <structname>v4l2_event_ctrl</structname></title> + <tgroup cols="4"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>changes</structfield></entry> + <entry></entry> + <entry>A bitmask that tells what has changed. See <xref linkend="changes-flags" />.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>type</structfield></entry> + <entry></entry> + <entry>The type of the control. See &v4l2-ctrl-type;.</entry> + </row> + <row> + <entry>union (anonymous)</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>__s32</entry> + <entry><structfield>value</structfield></entry> + <entry>The 32-bit value of the control for 32-bit control types. + This is 0 for string controls since the value of a string + cannot be passed using &VIDIOC-DQEVENT;.</entry> + </row> + <row> + <entry></entry> + <entry>__s64</entry> + <entry><structfield>value64</structfield></entry> + <entry>The 64-bit value of the control for 64-bit control types.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry></entry> + <entry>The control flags. See <xref linkend="control-flags" />.</entry> + </row> + <row> + <entry>__s32</entry> + <entry><structfield>minimum</structfield></entry> + <entry></entry> + <entry>The minimum value of the control. See &v4l2-queryctrl;.</entry> + </row> + <row> + <entry>__s32</entry> + <entry><structfield>maximum</structfield></entry> + <entry></entry> + <entry>The maximum value of the control. See &v4l2-queryctrl;.</entry> + </row> + <row> + <entry>__s32</entry> + <entry><structfield>step</structfield></entry> + <entry></entry> + <entry>The step value of the control. See &v4l2-queryctrl;.</entry> + </row> + <row> + <entry>__s32</entry> + <entry><structfield>default_value</structfield></entry> + <entry></entry> + <entry>The default value value of the control. See &v4l2-queryctrl;.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="v4l2-event-frame-sync"> + <title>struct <structname>v4l2_event_frame_sync</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>frame_sequence</structfield></entry> + <entry> + The sequence number of the frame being received. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="changes-flags"> + <title>Changes</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>V4L2_EVENT_CTRL_CH_VALUE</constant></entry> + <entry>0x0001</entry> + <entry>This control event was triggered because the value of the control + changed. Special case: if a button control is pressed, then this + event is sent as well, even though there is not explicit value + associated with a button control.</entry> + </row> + <row> + <entry><constant>V4L2_EVENT_CTRL_CH_FLAGS</constant></entry> + <entry>0x0002</entry> + <entry>This control event was triggered because the control flags + changed.</entry> + </row> + </tbody> + </tgroup> + </table> </refsect1> <refsect1> &return-value; diff --git a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml new file mode 100644 index 00000000000..7bde698760e --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml @@ -0,0 +1,88 @@ +<refentry id="vidioc-prepare-buf"> + <refmeta> + <refentrytitle>ioctl VIDIOC_PREPARE_BUF</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_PREPARE_BUF</refname> + <refpurpose>Prepare a buffer for I/O</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_buffer *<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_PREPARE_BUF</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>Applications can optionally call the +<constant>VIDIOC_PREPARE_BUF</constant> ioctl to pass ownership of the buffer +to the driver before actually enqueuing it, using the +<constant>VIDIOC_QBUF</constant> ioctl, and to prepare it for future I/O. +Such preparations may include cache invalidation or cleaning. Performing them +in advance saves time during the actual I/O. In case such cache operations are +not required, the application can use one of +<constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant> and +<constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant> flags to skip the respective +step.</para> + + <para>The <structname>v4l2_buffer</structname> structure is +specified in <xref linkend="buffer" />.</para> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EBUSY</errorcode></term> + <listitem> + <para>File I/O is in progress.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The buffer <structfield>type</structfield> is not +supported, or the <structfield>index</structfield> is out of bounds, +or no buffers have been allocated yet, or the +<structfield>userptr</structfield> or +<structfield>length</structfield> are invalid.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml index 677ea646c29..0ac0057a51c 100644 --- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml @@ -406,6 +406,15 @@ flag is typically present for relative controls or action controls where writing a value will cause the device to carry out a given action (⪚ motor control) but no meaningful value can be returned.</entry> </row> + <row> + <entry><constant>V4L2_CTRL_FLAG_VOLATILE</constant></entry> + <entry>0x0080</entry> + <entry>This control is volatile, which means that the value of the control +changes continuously. A typical example would be the current gain value if the device +is in auto-gain mode. In such a case the hardware calculates the gain value based on +the lighting conditions which can change over time. Note that setting a new value for +a volatile control will have no effect. The new value will just be ignored.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml index 69c0d8a2a3d..5c70b616d81 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml @@ -139,6 +139,22 @@ </entry> </row> <row> + <entry><constant>V4L2_EVENT_FRAME_SYNC</constant></entry> + <entry>4</entry> + <entry> + <para>Triggered immediately when the reception of a + frame has begun. This event has a + &v4l2-event-frame-sync; associated with it.</para> + + <para>If the hardware needs to be stopped in the case of a + buffer underrun it might not be able to generate this event. + In such cases the <structfield>frame_sequence</structfield> + field in &v4l2-event-frame-sync; will not be incremented. This + causes two consecutive frame sequence numbers to have n times + frame interval in between them.</para> + </entry> + </row> + <row> <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry> <entry>0x08000000</entry> <entry>Base event number for driver-private events.</entry> @@ -183,113 +199,6 @@ </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> - - <table frame="none" pgwide="1" id="v4l2-event-ctrl"> - <title>struct <structname>v4l2_event_ctrl</structname></title> - <tgroup cols="4"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>changes</structfield></entry> - <entry></entry> - <entry>A bitmask that tells what has changed. See <xref linkend="changes-flags" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry></entry> - <entry>The type of the control. See &v4l2-ctrl-type;.</entry> - </row> - <row> - <entry>union (anonymous)</entry> - <entry></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>__s32</entry> - <entry><structfield>value</structfield></entry> - <entry>The 32-bit value of the control for 32-bit control types. - This is 0 for string controls since the value of a string - cannot be passed using &VIDIOC-DQEVENT;.</entry> - </row> - <row> - <entry></entry> - <entry>__s64</entry> - <entry><structfield>value64</structfield></entry> - <entry>The 64-bit value of the control for 64-bit control types.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry></entry> - <entry>The control flags. See <xref linkend="control-flags" />.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>minimum</structfield></entry> - <entry></entry> - <entry>The minimum value of the control. See &v4l2-queryctrl;.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>maximum</structfield></entry> - <entry></entry> - <entry>The maximum value of the control. See &v4l2-queryctrl;.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>step</structfield></entry> - <entry></entry> - <entry>The step value of the control. See &v4l2-queryctrl;.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>default_value</structfield></entry> - <entry></entry> - <entry>The default value value of the control. See &v4l2-queryctrl;.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="changes-flags"> - <title>Changes</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_EVENT_CTRL_CH_VALUE</constant></entry> - <entry>0x0001</entry> - <entry>This control event was triggered because the value of the control - changed. Special case: if a button control is pressed, then this - event is sent as well, even though there is not explicit value - associated with a button control.</entry> - </row> - <row> - <entry><constant>V4L2_EVENT_CTRL_CH_FLAGS</constant></entry> - <entry>0x0002</entry> - <entry>This control event was triggered because the control flags - changed.</entry> - </row> - </tbody> - </tgroup> - </table> </refsect1> <refsect1> &return-value; |