diff options
Diffstat (limited to 'Documentation/DocBook/media')
| -rw-r--r-- | Documentation/DocBook/media/v4l/biblio.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/common.xml | 17 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/compat.xml | 21 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/dev-subdev.xml | 36 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/io.xml | 19 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/selection-api.xml | 34 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/selections-common.xml | 164 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/v4l2.xml | 5 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-create-bufs.xml | 8 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-g-frequency.xml | 6 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-g-selection.xml | 86 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-g-tuner.xml | 12 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-qbuf.xml | 9 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml | 18 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml | 79 |
15 files changed, 301 insertions, 215 deletions
diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index 7c49facecd25..1078e45f189f 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -194,7 +194,7 @@ in the frequency range from 87,5 to 108,0 MHz</title> <corpauthor>National Radio Systems Committee (<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor> </authorgroup> - <title>NTSC-4: United States RBDS Standard</title> + <title>NRSC-4: United States RBDS Standard</title> </biblioentry> <biblioentry id="iso12232"> diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index 4101aeb56540..b91d25313b63 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -464,14 +464,14 @@ The <structfield>type</structfield> field of the respective <structfield>tuner</structfield> field contains the index number of the tuner.</para> - <para>Radio devices have exactly one tuner with index zero, no + <para>Radio input devices have exactly one tuner with index zero, no video inputs.</para> <para>To query and change tuner properties applications use the &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The &v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also contains signal status information applicable when the tuner of the -current video input, or a radio tuner is queried. Note that +current video or radio input is queried. Note that <constant>VIDIOC_S_TUNER</constant> does not switch the current tuner, when there is more than one at all. The tuner is solely determined by the current video input. Drivers must support both ioctls and set the @@ -491,8 +491,17 @@ the modulator. The <structfield>type</structfield> field of the respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its <structfield>modulator</structfield> field contains the index number -of the modulator. This specification does not define radio output -devices.</para> +of the modulator.</para> + + <para>Radio output devices have exactly one modulator with index +zero, no video outputs.</para> + + <para>A video or radio device cannot support both a tuner and a +modulator. Two separate device nodes will have to be used for such +hardware, one that supports the tuner functionality and one that supports +the modulator functionality. The reason is a limitation with the +&VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency +is for a tuner or a modulator.</para> <para>To query and change modulator properties applications use the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index ea42ef824948..97b895151bb0 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2377,10 +2377,11 @@ that used it. It was originally scheduled for removal in 2.6.35. <para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.</para> </listitem> <listitem> - <para>Add selection API for extended control over cropping and -composing. Does not affect the compatibility of current drivers and -applications. See <link linkend="selection-api"> selection API </link> for -details.</para> + <para>Add selection API for extended control over cropping + and composing. Does not affect the compatibility of current + drivers and applications. See <link + linkend="selection-api"> selection API </link> for + details.</para> </listitem> </orderedlist> </section> @@ -2458,6 +2459,18 @@ details.</para> </orderedlist> </section> + <section> + <title>V4L2 in Linux 3.5</title> + <orderedlist> + <listitem> + <para>Replaced <structfield>input</structfield> in + <structname>v4l2_buffer</structname> by + <structfield>reserved2</structfield> and removed + <constant>V4L2_BUF_FLAG_INPUT</constant>.</para> + </listitem> + </orderedlist> + </section> + <section id="other"> <title>Relation of V4L2 to other Linux multimedia APIs</title> diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index 4afcbbec5eda..a3d9dd093268 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -276,7 +276,7 @@ </para> </section> - <section> + <section id="v4l2-subdev-selections"> <title>Selections: cropping, scaling and composition</title> <para>Many sub-devices support cropping frames on their input or output @@ -290,8 +290,8 @@ size. Both the coordinates and sizes are expressed in pixels.</para> <para>As for pad formats, drivers store try and active - rectangles for the selection targets of ACTUAL type <xref - linkend="v4l2-subdev-selection-targets">.</xref></para> + rectangles for the selection targets <xref + linkend="v4l2-selections-common" />.</para> <para>On sink pads, cropping is applied relative to the current pad format. The pad format represents the image size as @@ -308,7 +308,7 @@ <para>Scaling support is optional. When supported by a subdev, the crop rectangle on the subdev's sink pad is scaled to the size configured using the &VIDIOC-SUBDEV-S-SELECTION; IOCTL - using <constant>V4L2_SUBDEV_SEL_COMPOSE_ACTUAL</constant> + using <constant>V4L2_SEL_TGT_COMPOSE</constant> selection target on the same pad. If the subdev supports scaling but not composing, the top and left values are not used and must always be set to zero.</para> @@ -323,32 +323,32 @@ <para>The drivers should always use the closest possible rectangle the user requests on all selection targets, unless specifically told otherwise. - <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant> and - <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant> flags may be + <constant>V4L2_SEL_FLAG_GE</constant> and + <constant>V4L2_SEL_FLAG_LE</constant> flags may be used to round the image size either up or down. <xref - linkend="v4l2-subdev-selection-flags"></xref></para> + linkend="v4l2-selection-flags" /></para> </section> <section> <title>Types of selection targets</title> <section> - <title>ACTUAL targets</title> + <title>Actual targets</title> - <para>ACTUAL targets reflect the actual hardware configuration - at any point of time. There is a BOUNDS target - corresponding to every ACTUAL.</para> + <para>Actual targets (without a postfix) reflect the actual + hardware configuration at any point of time. There is a BOUNDS + target corresponding to every actual target.</para> </section> <section> <title>BOUNDS targets</title> - <para>BOUNDS targets is the smallest rectangle that contains - all valid ACTUAL rectangles. It may not be possible to set the - ACTUAL rectangle as large as the BOUNDS rectangle, however. - This may be because e.g. a sensor's pixel array is not - rectangular but cross-shaped or round. The maximum size may - also be smaller than the BOUNDS rectangle.</para> + <para>BOUNDS targets is the smallest rectangle that contains all + valid actual rectangles. It may not be possible to set the actual + rectangle as large as the BOUNDS rectangle, however. This may be + because e.g. a sensor's pixel array is not rectangular but + cross-shaped or round. The maximum size may also be smaller than the + BOUNDS rectangle.</para> </section> </section> @@ -362,7 +362,7 @@ performed by the user: the changes made will be propagated to any subsequent stages. If this behaviour is not desired, the user must set - <constant>V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG</constant> flag. This + <constant>V4L2_SEL_FLAG_KEEP_CONFIG</constant> flag. This flag causes no propagation of the changes are allowed in any circumstances. This may also cause the accessed rectangle to be adjusted by the driver, depending on the properties of the diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index fd6aca2922b6..1885cc0755cb 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -683,14 +683,12 @@ memory, set by the application. See <xref linkend="userp" /> for details. </row> <row> <entry>__u32</entry> - <entry><structfield>input</structfield></entry> + <entry><structfield>reserved2</structfield></entry> <entry></entry> - <entry>Some video capture drivers support rapid and -synchronous video input changes, a function useful for example in -video surveillance applications. For this purpose applications set the -<constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the -number of a video input as in &v4l2-input; field -<structfield>index</structfield>.</entry> + <entry>A place holder for future extensions and custom +(driver defined) buffer types +<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher. Applications +should set this to 0.</entry> </row> <row> <entry>__u32</entry> @@ -923,13 +921,6 @@ Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant> ioctl is called.</entry> </row> <row> - <entry><constant>V4L2_BUF_FLAG_INPUT</constant></entry> - <entry>0x0200</entry> - <entry>The <structfield>input</structfield> field is valid. -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 diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index b299e4779354..e7ed5077834d 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -53,11 +53,11 @@ cropping and composing rectangles have the same size.</para> </mediaobject> </figure> -For complete list of the available selection targets see table <xref -linkend="v4l2-sel-target"/> - </section> + See <xref linkend="v4l2-selection-targets" /> for more + information. + <section> <title>Configuration</title> @@ -74,7 +74,7 @@ cropping/composing rectangles may have to be aligned, and both the source and the sink may have arbitrary upper and lower size limits. Therefore, as usual, drivers are expected to adjust the requested parameters and return the actual values selected. An application can control the rounding behaviour using <link -linkend="v4l2-sel-flags"> constraint flags </link>.</para> +linkend="v4l2-selection-flags"> constraint flags </link>.</para> <section> @@ -91,7 +91,7 @@ top/left corner at position <constant> (0,0) </constant>. The rectangle's coordinates are expressed in pixels.</para> <para>The top left corner, width and height of the source rectangle, that is -the area actually sampled, is given by the <constant> V4L2_SEL_TGT_CROP_ACTIVE +the area actually sampled, is given by the <constant> V4L2_SEL_TGT_CROP </constant> target. It uses the same coordinate system as <constant> V4L2_SEL_TGT_CROP_BOUNDS </constant>. The active cropping area must lie completely inside the capture boundaries. The driver may further adjust the @@ -111,13 +111,13 @@ height are equal to the image size set by <constant> VIDIOC_S_FMT </constant>. </para> <para>The part of a buffer into which the image is inserted by the hardware is -controlled by the <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target. +controlled by the <constant> V4L2_SEL_TGT_COMPOSE </constant> target. The rectangle's coordinates are also expressed in the same coordinate system as the bounds rectangle. The composing rectangle must lie completely inside bounds rectangle. The driver must adjust the composing rectangle to fit to the bounding limits. Moreover, the driver can perform other adjustments according to hardware limitations. The application can control rounding behaviour using -<link linkend="v4l2-sel-flags"> constraint flags </link>.</para> +<link linkend="v4l2-selection-flags"> constraint flags </link>.</para> <para>For capture devices the default composing rectangle is queried using <constant> V4L2_SEL_TGT_COMPOSE_DEFAULT </constant>. It is usually equal to the @@ -125,7 +125,7 @@ bounding rectangle.</para> <para>The part of a buffer that is modified by the hardware is given by <constant> V4L2_SEL_TGT_COMPOSE_PADDED </constant>. It contains all pixels -defined using <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> plus all +defined using <constant> V4L2_SEL_TGT_COMPOSE </constant> plus all padding data modified by hardware during insertion process. All pixels outside this rectangle <emphasis>must not</emphasis> be changed by the hardware. The content of pixels that lie inside the padded area but outside active area is @@ -153,7 +153,7 @@ specified using <constant> VIDIOC_S_FMT </constant> ioctl.</para> <para>The top left corner, width and height of the source rectangle, that is the area from which image date are processed by the hardware, is given by the -<constant> V4L2_SEL_TGT_CROP_ACTIVE </constant>. Its coordinates are expressed +<constant> V4L2_SEL_TGT_CROP </constant>. Its coordinates are expressed in in the same coordinate system as the bounds rectangle. The active cropping area must lie completely inside the crop boundaries and the driver may further adjust the requested size and/or position according to hardware @@ -165,7 +165,7 @@ bounding rectangle.</para> <para>The part of a video signal or graphics display where the image is inserted by the hardware is controlled by <constant> -V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target. The rectangle's coordinates +V4L2_SEL_TGT_COMPOSE </constant> target. The rectangle's coordinates are expressed in pixels. The composing rectangle must lie completely inside the bounds rectangle. The driver must adjust the area to fit to the bounding limits. Moreover, the driver can perform other adjustments according to @@ -184,7 +184,7 @@ such a padded area is driver-dependent feature not covered by this document. Driver developers are encouraged to keep padded rectangle equal to active one. The padded target is accessed by the <constant> V4L2_SEL_TGT_COMPOSE_PADDED </constant> identifier. It must contain all pixels from the <constant> -V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target.</para> +V4L2_SEL_TGT_COMPOSE </constant> target.</para> </section> @@ -193,8 +193,8 @@ V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target.</para> <title>Scaling control</title> <para>An application can detect if scaling is performed by comparing the width -and the height of rectangles obtained using <constant> V4L2_SEL_TGT_CROP_ACTIVE -</constant> and <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> targets. If +and the height of rectangles obtained using <constant> V4L2_SEL_TGT_CROP +</constant> and <constant> V4L2_SEL_TGT_COMPOSE </constant> targets. If these are not equal then the scaling is applied. The application can compute the scaling ratios using these values.</para> @@ -252,7 +252,7 @@ area)</para> ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); if (ret) exit(-1); - sel.target = V4L2_SEL_TGT_CROP_ACTIVE; + sel.target = V4L2_SEL_TGT_CROP; ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); if (ret) exit(-1); @@ -281,7 +281,7 @@ area)</para> r.left = sel.r.width / 4; r.top = sel.r.height / 4; sel.r = r; - sel.target = V4L2_SEL_TGT_COMPOSE_ACTIVE; + sel.target = V4L2_SEL_TGT_COMPOSE; sel.flags = V4L2_SEL_FLAG_LE; ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); if (ret) @@ -298,11 +298,11 @@ V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> for other devices</para> &v4l2-selection; compose = { .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, - .target = V4L2_SEL_TGT_COMPOSE_ACTIVE, + .target = V4L2_SEL_TGT_COMPOSE, }; &v4l2-selection; crop = { .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, - .target = V4L2_SEL_TGT_CROP_ACTIVE, + .target = V4L2_SEL_TGT_CROP, }; double hscale, vscale; diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml new file mode 100644 index 000000000000..7502f784b8cc --- /dev/null +++ b/Documentation/DocBook/media/v4l/selections-common.xml @@ -0,0 +1,164 @@ +<section id="v4l2-selections-common"> + + <title>Common selection definitions</title> + + <para>While the <link linkend="selection-api">V4L2 selection + API</link> and <link linkend="v4l2-subdev-selections">V4L2 subdev + selection APIs</link> are very similar, there's one fundamental + difference between the two. On sub-device API, the selection + rectangle refers to the media bus format, and is bound to a + sub-device's pad. On the V4L2 interface the selection rectangles + refer to the in-memory pixel format.</para> + + <para>This section defines the common definitions of the + selection interfaces on the two APIs.</para> + + <section id="v4l2-selection-targets"> + + <title>Selection targets</title> + + <para>The precise meaning of the selection targets may be + dependent on which of the two interfaces they are used.</para> + + <table pgwide="1" frame="none" id="v4l2-selection-targets-table"> + <title>Selection target definitions</title> + <tgroup cols="5"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + &cs-def; + <thead> + <row rowsep="1"> + <entry align="left">Target name</entry> + <entry align="left">id</entry> + <entry align="left">Definition</entry> + <entry align="left">Valid for V4L2</entry> + <entry align="left">Valid for V4L2 subdev</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_SEL_TGT_CROP</constant></entry> + <entry>0x0000</entry> + <entry>Crop rectangle. Defines the cropped area.</entry> + <entry>Yes</entry> + <entry>Yes</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry> + <entry>0x0001</entry> + <entry>Suggested cropping rectangle that covers the "whole picture".</entry> + <entry>Yes</entry> + <entry>No</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry> + <entry>0x0002</entry> + <entry>Bounds of the crop rectangle. All valid crop + rectangles fit inside the crop bounds rectangle. + </entry> + <entry>Yes</entry> + <entry>Yes</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry> + <entry>0x0100</entry> + <entry>Compose rectangle. Used to configure scaling + and composition.</entry> + <entry>Yes</entry> + <entry>Yes</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry> + <entry>0x0101</entry> + <entry>Suggested composition rectangle that covers the "whole picture".</entry> + <entry>Yes</entry> + <entry>No</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry> + <entry>0x0102</entry> + <entry>Bounds of the compose rectangle. All valid compose + rectangles fit inside the compose bounds rectangle.</entry> + <entry>Yes</entry> + <entry>Yes</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry> + <entry>0x0103</entry> + <entry>The active area and all padding pixels that are inserted or + modified by hardware.</entry> + <entry>Yes</entry> + <entry>No</entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + + <section id="v4l2-selection-flags"> + + <title>Selection flags</title> + + <table pgwide="1" frame="none" id="v4l2-selection-flags-table"> + <title>Selection flag definitions</title> + <tgroup cols="5"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + &cs-def; + <thead> + <row rowsep="1"> + <entry align="left">Flag name</entry> + <entry align="left">id</entry> + <entry align="left">Definition</entry> + <entry align="left">Valid for V4L2</entry> + <entry align="left">Valid for V4L2 subdev</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_SEL_FLAG_GE</constant></entry> + <entry>(1 << 0)</entry> + <entry>Suggest the driver it should choose greater or + equal rectangle (in size) than was requested. Albeit the + driver may choose a lesser size, it will only do so due to + hardware limitations. Without this flag (and + <constant>V4L2_SEL_FLAG_LE</constant>) the + behaviour is to choose the closest possible + rectangle.</entry> + <entry>Yes</entry> + <entry>Yes</entry> + </row> + <row> + <entry><constant>V4L2_SEL_FLAG_LE</constant></entry> + <entry>(1 << 1)</entry> + <entry>Suggest the driver it + should choose lesser or equal rectangle (in size) than was + requested. Albeit the driver may choose a greater size, it + will only do so due to hardware limitations.</entry> + <entry>Yes</entry> + <entry>Yes</entry> + </row> + <row> + <entry><constant>V4L2_SEL_FLAG_KEEP_CONFIG</constant></entry> + <entry>(1 << 2)</entry> + <entry>The configuration must not be propagated to any + further processing steps. If this flag is not given, the + configuration is propagated inside the subdevice to all + further processing steps.</entry> + <entry>No</entry> + <entry>Yes</entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + +</section> diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 008c2d73a484..36bafc48e03b 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -589,6 +589,11 @@ and discussions on the V4L mailing list.</revremark> &sub-write; </appendix> + <appendix> + <title>Common definitions for V4L2 and V4L2 subdev interfaces</title> + &sub-selections-common; + </appendix> + <appendix id="videodev"> <title>Video For Linux Two Header File</title> &sub-videodev2-h; diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index a2474ecb574a..5e73b1c8d095 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -97,7 +97,13 @@ information.</para> <row> <entry>__u32</entry> <entry><structfield>count</structfield></entry> - <entry>The number of buffers requested or granted.</entry> + <entry>The number of buffers requested or granted. If count == 0, then + <constant>VIDIOC_CREATE_BUFS</constant> will set <structfield>index</structfield> + to the current number of created buffers, and it will check the validity of + <structfield>memory</structfield> and <structfield>format.type</structfield>. + If those are invalid -1 is returned and errno is set to &EINVAL;, + otherwise <constant>VIDIOC_CREATE_BUFS</constant> returns 0. It will + never set errno to &EBUSY; in this particular case.</entry> </row> <row> <entry>__u32</entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml index 69c178a4d205..40e58a42eb26 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml @@ -135,6 +135,12 @@ bounds or the value in the <structfield>type</structfield> field is wrong.</para> </listitem> </varlistentry> + <varlistentry> + <term><errorcode>EBUSY</errorcode></term> + <listitem> + <para>A hardware seek is in progress.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> </refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index bb04eff75f45..f76d8a6d9b92 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -65,9 +65,9 @@ Do not use multiplanar buffers. Use <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE </constant>. Use <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> instead of <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE </constant>. The next step is setting the value of &v4l2-selection; <structfield>target</structfield> field -to <constant> V4L2_SEL_TGT_CROP_ACTIVE </constant> (<constant> -V4L2_SEL_TGT_COMPOSE_ACTIVE </constant>). Please refer to table <xref -linkend="v4l2-sel-target" /> or <xref linkend="selection-api" /> for additional +to <constant> V4L2_SEL_TGT_CROP </constant> (<constant> +V4L2_SEL_TGT_COMPOSE </constant>). Please refer to table <xref +linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> for additional targets. The <structfield>flags</structfield> and <structfield>reserved </structfield> fields of &v4l2-selection; are ignored and they must be filled with zeros. The driver fills the rest of the structure or @@ -86,9 +86,9 @@ use multiplanar buffers. Use <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE </constant>. Use <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> instead of <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE </constant>. The next step is setting the value of &v4l2-selection; <structfield>target</structfield> to -<constant>V4L2_SEL_TGT_CROP_ACTIVE</constant> (<constant> -V4L2_SEL_TGT_COMPOSE_ACTIVE </constant>). Please refer to table <xref -linkend="v4l2-sel-target" /> or <xref linkend="selection-api" /> for additional +<constant>V4L2_SEL_TGT_CROP</constant> (<constant> +V4L2_SEL_TGT_COMPOSE </constant>). Please refer to table <xref +linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> for additional targets. The &v4l2-rect; <structfield>r</structfield> rectangle need to be set to the desired active area. Field &v4l2-selection; <structfield> reserved </structfield> is ignored and must be filled with zeros. The driver may adjust @@ -154,74 +154,8 @@ exist no rectangle </emphasis> that satisfies the constraints.</para> </refsect1> - <refsect1> - <table frame="none" pgwide="1" id="v4l2-sel-target"> - <title>Selection targets.</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_SEL_TGT_CROP_ACTIVE</constant></entry> - <entry>0x0000</entry> - <entry>The area that is currently cropped by hardware.</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry> - <entry>0x0001</entry> - <entry>Suggested cropping rectangle that covers the "whole picture".</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry> - <entry>0x0002</entry> - <entry>Limits for the cropping rectangle.</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_COMPOSE_ACTIVE</constant></entry> - <entry>0x0100</entry> - <entry>The area to which data is composed by hardware.</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry> - <entry>0x0101</entry> - <entry>Suggested composing rectangle that covers the "whole picture".</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry> - <entry>0x0102</entry> - <entry>Limits for the composing rectangle.</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry> - <entry>0x0103</entry> - <entry>The active area and all padding pixels that are inserted or modified by hardware.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - <table frame="none" pgwide="1" id="v4l2-sel-flags"> - <title>Selection constraint flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_SEL_FLAG_GE</constant></entry> - <entry>0x00000001</entry> - <entry>Indicates that the adjusted rectangle must contain the original - &v4l2-selection; <structfield>r</structfield> rectangle.</entry> - </row> - <row> - <entry><constant>V4L2_SEL_FLAG_LE</constant></entry> - <entry>0x00000002</entry> - <entry>Indicates that the adjusted rectangle must be inside the original - &v4l2-rect; <structfield>r</structfield> rectangle.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> + <para>Selection targets and flags are documented in <xref + linkend="v4l2-selections-common"/>.</para> <section> <figure id="sel-const-adjust"> @@ -252,14 +186,14 @@ exist no rectangle </emphasis> that satisfies the constraints.</para> <row> <entry>__u32</entry> <entry><structfield>target</structfield></entry> - <entry>Used to select between <link linkend="v4l2-sel-target"> cropping + <entry>Used to select between <link linkend="v4l2-selections-common"> cropping and composing rectangles</link>.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> <entry>Flags controlling the selection rectangle adjustments, refer to - <link linkend="v4l2-sel-flags">selection flags</link>.</entry> + <link linkend="v4l2-selection-flags">selection flags</link>.</entry> </row> <row> <entry>&v4l2-rect;</entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml index 62a1aa200a36..95d5371c1709 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml @@ -276,6 +276,18 @@ can or must be switched. (B/G PAL tuners for example are typically not <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> </row> <row> + <entry><constant>V4L2_TUNER_CAP_HWSEEK_BOUNDED</constant></entry> + <entry>0x0004</entry> + <entry>If set, then this tuner supports the hardware seek functionality + where the seek stops when it reaches the end of the frequency range.</entry> + </row> + <row> + <entry><constant>V4L2_TUNER_CAP_HWSEEK_WRAP</constant></entry> + <entry>0x0008</entry> + <entry>If set, then this tuner supports the hardware seek functionality + where the seek wraps around when it reaches the end of the frequency range.</entry> + </row> + <row> <entry><constant>V4L2_TUNER_CAP_STEREO</constant></entry> <entry>0x0010</entry> <entry>Stereo audio reception is supported.</entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 9caa49af580f..77ff5be0809d 100644 --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml @@ -71,12 +71,9 @@ initialize the <structfield>bytesused</structfield>, <structfield>field</structfield> and <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. When using +Applications must also set <structfield>flags</structfield> to 0. +The <structfield>reserved2</structfield> and +<structfield>reserved</structfield> fields must be set to 0. When using the <link linkend="planar-apis">multi-planar API</link>, the <structfield>m.planes</structfield> field must contain a userspace pointer to a filled-in array of &v4l2-plane; and the <structfield>length</structfield> diff --git a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml index 407dfceb71f0..f4db44d0d95a 100644 --- a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml +++ b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml @@ -58,6 +58,9 @@ To do this applications initialize the <structfield>tuner</structfield>, call the <constant>VIDIOC_S_HW_FREQ_SEEK</constant> ioctl with a pointer to this structure.</para> + <para>If an error is returned, then the original frequency will + be restored.</para> + <para>This ioctl is supported if the <constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability is set.</para> <table pgwide="1" frame="none" id="v4l2-hw-freq-seek"> @@ -87,7 +90,10 @@ field and the &v4l2-tuner; <structfield>index</structfield> field.</entry> <row> <entry>__u32</entry> <entry><structfield>wrap_around</structfield></entry> - <entry>If non-zero, wrap around when at the end of the frequency range, else stop seeking.</entry> + <entry>If non-zero, wrap around when at the end of the frequency range, else stop seeking. + The &v4l2-tuner; <structfield>capability</structfield> field will tell you what the + hardware supports. + </entry> </row> <row> <entry>__u32</entry> @@ -118,9 +124,15 @@ wrong.</para> </listitem> </varlistentry> <varlistentry> - <term><errorcode>EAGAIN</errorcode></term> + <term><errorcode>ENODATA</errorcode></term> + <listitem> + <para>The hardware seek found no channels.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EBUSY</errorcode></term> <listitem> - <para>The ioctl timed-out. Try again.</para> + <para>Another hardware seek is already in progress.</para> </listitem> </varlistentry> </variablelist> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index 208e9f0da3f3..f33cc814a01d 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -72,10 +72,10 @@ <section> <title>Types of selection targets</title> - <para>There are two types of selection targets: actual and bounds. - The ACTUAL targets are the targets which configure the hardware. - The BOUNDS target will return a rectangle that contain all - possible ACTUAL rectangles.</para> + <para>There are two types of selection targets: actual and bounds. The + actual targets are the targets which configure the hardware. The BOUNDS + target will return a rectangle that contain all possible actual + rectangles.</para> </section> <section> @@ -87,71 +87,8 @@ <constant>EINVAL</constant>.</para> </section> - <table pgwide="1" frame="none" id="v4l2-subdev-selection-targets"> - <title>V4L2 subdev selection targets</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL</constant></entry> - <entry>0x0000</entry> - <entry>Actual crop. Defines the cropping - performed by the processing step.</entry> - </row> - <row> - <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS</constant></entry> - <entry>0x0002</entry> - <entry>Bounds of the crop rectangle.</entry> - </row> - <row> - <entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL</constant></entry> - <entry>0x0100</entry> - <entry>Actual compose rectangle. Used to configure scaling - on sink pads and composition on source pads.</entry> - </row> - <row> - <entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS</constant></entry> - <entry>0x0102</entry> - <entry>Bounds of the compose rectangle.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-subdev-selection-flags"> - <title>V4L2 subdev selection flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant></entry> - <entry>(1 << 0)</entry> <entry>Suggest the driver it - should choose greater or equal rectangle (in size) than - was requested. Albeit the driver may choose a lesser size, - it will only do so due to hardware limitations. Without - this flag (and - <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant>) the - behaviour is to choose the closest possible - rectangle.</entry> - </row> - <row> - <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant></entry> - <entry>(1 << 1)</entry> <entry>Suggest the driver it - should choose lesser or equal rectangle (in size) than was - requested. Albeit the driver may choose a greater size, it - will only do so due to hardware limitations.</entry> - </row> - <row> - <entry><constant>V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG</constant></entry> - <entry>(1 << 2)</entry> - <entry>The configuration should not be propagated to any - further processing steps. If this flag is not given, the - configuration is propagated inside the subdevice to all - further processing steps.</entry> - </row> - </tbody> - </tgroup> - </table> + <para>Selection targets and flags are documented in <xref + linkend="v4l2-selections-common"/>.</para> <table pgwide="1" frame="none" id="v4l2-subdev-selection"> <title>struct <structname>v4l2_subdev_selection</structname></title> @@ -173,13 +110,13 @@ <entry>__u32</entry> <entry><structfield>target</structfield></entry> <entry>Target selection rectangle. See - <xref linkend="v4l2-subdev-selection-targets">.</xref>.</entry> + <xref linkend="v4l2-selections-common" />.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> <entry>Flags. See - <xref linkend="v4l2-subdev-selection-flags">.</xref></entry> + <xref linkend="v4l2-selection-flags" />.</entry> </row> <row> <entry>&v4l2-rect;</entry> |