summaryrefslogtreecommitdiff
path: root/Documentation/DocBook/media/v4l
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/media/v4l')
-rw-r--r--Documentation/DocBook/media/v4l/controls.xml4
-rw-r--r--Documentation/DocBook/media/v4l/io.xml26
-rw-r--r--Documentation/DocBook/media/v4l/media-func-open.xml2
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y16-be.xml81
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt.xml134
-rw-r--r--Documentation/DocBook/media/v4l/remote_controllers.xml2
-rw-r--r--Documentation/DocBook/media/v4l/subdev-formats.xml12
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-create-bufs.xml3
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml12
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dqevent.xml5
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml10
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml3
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml3
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-expbuf.xml3
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml4
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-edid.xml11
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-selection.xml2
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-qbuf.xml10
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml3
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-querybuf.xml3
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-reqbufs.xml4
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml3
22 files changed, 286 insertions, 54 deletions
diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml
index 4e9462f1ab4c..6e1667b5f3eb 100644
--- a/Documentation/DocBook/media/v4l/controls.xml
+++ b/Documentation/DocBook/media/v4l/controls.xml
@@ -4863,7 +4863,7 @@ interface and may change in the future.</para>
</note>
<para>
- The Image Source control class is intended for low-level control of
+ The Image Process control class is intended for low-level control of
image processing functions. Unlike
<constant>V4L2_CID_IMAGE_SOURCE_CLASS</constant>, the controls in
this class affect processing the image, and do not control capturing
@@ -4871,7 +4871,7 @@ interface and may change in the future.</para>
</para>
<table pgwide="1" frame="none" id="image-process-control-id">
- <title>Image Source Control IDs</title>
+ <title>Image Process Control IDs</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="1*" />
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
index 1c17f802b471..7bbc2a48911e 100644
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -841,15 +841,15 @@ is the file descriptor associated with a DMABUF buffer.</entry>
<entry>__u32</entry>
<entry><structfield>reserved2</structfield></entry>
<entry></entry>
- <entry>A place holder for future extensions. Applications
-should set this to 0.</entry>
+ <entry>A place holder for future extensions. Drivers and applications
+must set this to 0.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield></entry>
<entry></entry>
- <entry>A place holder for future extensions. Applications
-should set this to 0.</entry>
+ <entry>A place holder for future extensions. Drivers and applications
+must set this to 0.</entry>
</row>
</tbody>
</tgroup>
@@ -930,8 +930,8 @@ should set this to 0.</entry>
<entry>__u32</entry>
<entry><structfield>reserved[11]</structfield></entry>
<entry></entry>
- <entry>Reserved for future use. Should be zeroed by an
- application.</entry>
+ <entry>Reserved for future use. Should be zeroed by drivers and
+ applications.</entry>
</row>
</tbody>
</tgroup>
@@ -1129,6 +1129,18 @@ 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>
<row>
+ <entry><constant>V4L2_BUF_FLAG_LAST</constant></entry>
+ <entry>0x00100000</entry>
+ <entry>Last buffer produced by the hardware. mem2mem codec drivers
+set this flag on the capture queue for the last buffer when the
+<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link> or
+<link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Due to hardware
+limitations, the last buffer may be empty. In this case the driver will set the
+<structfield>bytesused</structfield> field to 0, regardless of the format. Any
+Any subsequent call to the <link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl
+will not block anymore, but return an &EPIPE;.</entry>
+ </row>
+ <row>
<entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry>
<entry>0x0000e000</entry>
<entry>Mask for timestamp types below. To test the
@@ -1155,7 +1167,7 @@ in which case caches have not been used.</entry>
<entry>The buffer timestamp has been taken from the
<constant>CLOCK_MONOTONIC</constant> clock. To access the
same clock outside V4L2, use
- <function>clock_gettime(2)</function> .</entry>
+ <function>clock_gettime(2)</function>.</entry>
</row>
<row>
<entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry>
diff --git a/Documentation/DocBook/media/v4l/media-func-open.xml b/Documentation/DocBook/media/v4l/media-func-open.xml
index f7df034dc9ed..122374a3e894 100644
--- a/Documentation/DocBook/media/v4l/media-func-open.xml
+++ b/Documentation/DocBook/media/v4l/media-func-open.xml
@@ -44,7 +44,7 @@
<para>To open a media device applications call <function>open()</function>
with the desired device name. The function has no side effects; the device
configuration remain unchanged.</para>
- <para>When the device is opened in read-only mode, attemps to modify its
+ <para>When the device is opened in read-only mode, attempts to modify its
configuration will result in an error, and <varname>errno</varname> will be
set to <errorcode>EBADF</errorcode>.</para>
</refsect1>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-y16-be.xml b/Documentation/DocBook/media/v4l/pixfmt-y16-be.xml
new file mode 100644
index 000000000000..cea53e1eaa43
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-y16-be.xml
@@ -0,0 +1,81 @@
+<refentry id="V4L2-PIX-FMT-Y16-BE">
+ <refmeta>
+ <refentrytitle>V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 &lt;&lt; 31))</refentrytitle>
+ &manvol;
+ </refmeta>
+ <refnamediv>
+ <refname><constant>V4L2_PIX_FMT_Y16_BE</constant></refname>
+ <refpurpose>Grey-scale image</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+
+ <para>This is a grey-scale image with a depth of 16 bits per
+pixel. The most significant byte is stored at lower memory addresses
+(big-endian). Note the actual sampling precision may be lower than
+16 bits, for example 10 bits per pixel with values in range 0 to
+1023.</para>
+
+ <example>
+ <title><constant>V4L2_PIX_FMT_Y16_BE</constant> 4 &times; 4
+pixel image</title>
+
+ <formalpara>
+ <title>Byte Order.</title>
+ <para>Each cell is one byte.
+ <informaltable frame="none">
+ <tgroup cols="9" align="center">
+ <colspec align="left" colwidth="2*" />
+ <tbody valign="top">
+ <row>
+ <entry>start&nbsp;+&nbsp;0:</entry>
+ <entry>Y'<subscript>00high</subscript></entry>
+ <entry>Y'<subscript>00low</subscript></entry>
+ <entry>Y'<subscript>01high</subscript></entry>
+ <entry>Y'<subscript>01low</subscript></entry>
+ <entry>Y'<subscript>02high</subscript></entry>
+ <entry>Y'<subscript>02low</subscript></entry>
+ <entry>Y'<subscript>03high</subscript></entry>
+ <entry>Y'<subscript>03low</subscript></entry>
+ </row>
+ <row>
+ <entry>start&nbsp;+&nbsp;8:</entry>
+ <entry>Y'<subscript>10high</subscript></entry>
+ <entry>Y'<subscript>10low</subscript></entry>
+ <entry>Y'<subscript>11high</subscript></entry>
+ <entry>Y'<subscript>11low</subscript></entry>
+ <entry>Y'<subscript>12high</subscript></entry>
+ <entry>Y'<subscript>12low</subscript></entry>
+ <entry>Y'<subscript>13high</subscript></entry>
+ <entry>Y'<subscript>13low</subscript></entry>
+ </row>
+ <row>
+ <entry>start&nbsp;+&nbsp;16:</entry>
+ <entry>Y'<subscript>20high</subscript></entry>
+ <entry>Y'<subscript>20low</subscript></entry>
+ <entry>Y'<subscript>21high</subscript></entry>
+ <entry>Y'<subscript>21low</subscript></entry>
+ <entry>Y'<subscript>22high</subscript></entry>
+ <entry>Y'<subscript>22low</subscript></entry>
+ <entry>Y'<subscript>23high</subscript></entry>
+ <entry>Y'<subscript>23low</subscript></entry>
+ </row>
+ <row>
+ <entry>start&nbsp;+&nbsp;24:</entry>
+ <entry>Y'<subscript>30high</subscript></entry>
+ <entry>Y'<subscript>30low</subscript></entry>
+ <entry>Y'<subscript>31high</subscript></entry>
+ <entry>Y'<subscript>31low</subscript></entry>
+ <entry>Y'<subscript>32high</subscript></entry>
+ <entry>Y'<subscript>32low</subscript></entry>
+ <entry>Y'<subscript>33high</subscript></entry>
+ <entry>Y'<subscript>33low</subscript></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </formalpara>
+ </example>
+ </refsect1>
+</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml
index fcde4e20205e..965ea916784a 100644
--- a/Documentation/DocBook/media/v4l/pixfmt.xml
+++ b/Documentation/DocBook/media/v4l/pixfmt.xml
@@ -157,6 +157,14 @@ see <xref linkend="colorspaces" />.</entry>
capture streams and by the application for output streams,
see <xref linkend="colorspaces" />.</entry>
</row>
+ <row>
+ <entry>&v4l2-xfer-func;</entry>
+ <entry><structfield>xfer_func</structfield></entry>
+ <entry>This information supplements the
+<structfield>colorspace</structfield> and must be set by the driver for
+capture streams and by the application for output streams,
+see <xref linkend="colorspaces" />.</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -190,8 +198,8 @@ see <xref linkend="colorspaces" />.</entry>
<row>
<entry>__u16</entry>
<entry><structfield>reserved[6]</structfield></entry>
- <entry>Reserved for future extensions. Should be zeroed by the
- application.</entry>
+ <entry>Reserved for future extensions. Should be zeroed by drivers and
+ applications.</entry>
</row>
</tbody>
</tgroup>
@@ -264,11 +272,19 @@ see <xref linkend="colorspaces" />.</entry>
capture streams and by the application for output streams,
see <xref linkend="colorspaces" />.</entry>
</row>
+ <row>
+ <entry>&v4l2-xfer-func;</entry>
+ <entry><structfield>xfer_func</structfield></entry>
+ <entry>This information supplements the
+<structfield>colorspace</structfield> and must be set by the driver for
+capture streams and by the application for output streams,
+see <xref linkend="colorspaces" />.</entry>
+ </row>
<row>
<entry>__u8</entry>
- <entry><structfield>reserved[8]</structfield></entry>
- <entry>Reserved for future extensions. Should be zeroed by the
- application.</entry>
+ <entry><structfield>reserved[7]</structfield></entry>
+ <entry>Reserved for future extensions. Should be zeroed by drivers
+ and applications.</entry>
</row>
</tbody>
</tgroup>
@@ -476,15 +492,16 @@ is also very useful.</para>
<section>
<title>Defining Colorspaces in V4L2</title>
- <para>In V4L2 colorspaces are defined by three values. The first is the colorspace
-identifier (&v4l2-colorspace;) which defines the chromaticities, the transfer
+ <para>In V4L2 colorspaces are defined by four values. The first is the colorspace
+identifier (&v4l2-colorspace;) which defines the chromaticities, the default transfer
function, the default Y'CbCr encoding and the default quantization method. The second
-is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;) to specify non-standard
-Y'CbCr encodings and the third is the quantization identifier (&v4l2-quantization;)
-to specify non-standard quantization methods. Most of the time only the colorspace
-field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to be filled in. Note
-that the default R'G'B' quantization is full range for all colorspaces except for
-BT.2020 which uses limited range R'G'B' quantization.</para>
+is the transfer function identifier (&v4l2-xfer-func;) to specify non-standard
+transfer functions. The third is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;)
+to specify non-standard Y'CbCr encodings and the fourth is the quantization identifier
+(&v4l2-quantization;) to specify non-standard quantization methods. Most of the time
+only the colorspace field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to
+be filled in. Note that the default R'G'B' quantization is full range for all
+colorspaces except for BT.2020 which uses limited range R'G'B' quantization.</para>
<table pgwide="1" frame="none" id="v4l2-colorspace">
<title>V4L2 Colorspaces</title>
@@ -498,6 +515,11 @@ BT.2020 which uses limited range R'G'B' quantization.</para>
</thead>
<tbody valign="top">
<row>
+ <entry><constant>V4L2_COLORSPACE_DEFAULT</constant></entry>
+ <entry>The default colorspace. This can be used by applications to let the
+ driver fill in the colorspace.</entry>
+ </row>
+ <row>
<entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry>
<entry>See <xref linkend="col-smpte-170m" />.</entry>
</row>
@@ -533,6 +555,52 @@ BT.2020 which uses limited range R'G'B' quantization.</para>
<entry><constant>V4L2_COLORSPACE_JPEG</constant></entry>
<entry>See <xref linkend="col-jpeg" />.</entry>
</row>
+ <row>
+ <entry><constant>V4L2_COLORSPACE_RAW</constant></entry>
+ <entry>The raw colorspace. This is used for raw image capture where
+ the image is minimally processed and is using the internal colorspace
+ of the device. The software that processes an image using this
+ 'colorspace' will have to know the internals of the capture device.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1" frame="none" id="v4l2-xfer-func">
+ <title>V4L2 Transfer Function</title>
+ <tgroup cols="2" align="left">
+ &cs-def;
+ <thead>
+ <row>
+ <entry>Identifier</entry>
+ <entry>Details</entry>
+ </row>
+ </thead>
+ <tbody valign="top">
+ <row>
+ <entry><constant>V4L2_XFER_FUNC_DEFAULT</constant></entry>
+ <entry>Use the default transfer function as defined by the colorspace.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_XFER_FUNC_709</constant></entry>
+ <entry>Use the Rec. 709 transfer function.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_XFER_FUNC_SRGB</constant></entry>
+ <entry>Use the sRGB transfer function.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_XFER_FUNC_ADOBERGB</constant></entry>
+ <entry>Use the AdobeRGB transfer function.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_XFER_FUNC_SMPTE240M</constant></entry>
+ <entry>Use the SMPTE 240M transfer function.</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_XFER_FUNC_NONE</constant></entry>
+ <entry>Do not use a transfer function (i.e. use linear RGB values).</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -624,7 +692,8 @@ is mapped to [16&hellip;235]. Cb and Cr are mapped from [-0.5&hellip;0.5] to [16
<section id="col-smpte-170m">
<title>Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title>
<para>The <xref linkend="smpte170m" /> standard defines the colorspace used by NTSC and PAL and by SDTV
-in general. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>.
+in general. The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>.
+The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>.
The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and
the white reference are:</para>
<table frame="none">
@@ -706,7 +775,8 @@ rarely seen.</para>
<section id="col-rec709">
<title>Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title>
- <para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general. The default
+ <para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general.
+The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. The default
Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. The default Y'CbCr quantization is
limited range. The chromaticities of the primary colors and the white reference are:</para>
<table frame="none">
@@ -817,9 +887,11 @@ The xvYCC encodings always use full range quantization.</para>
<section id="col-srgb">
<title>Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title>
- <para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams and computer graphics. The
-default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr quantization
-is full range. The chromaticities of the primary colors and the white reference are:</para>
+ <para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams
+and computer graphics. The default transfer function is <constant>V4L2_XFER_FUNC_SRGB</constant>.
+The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr
+quantization is full range. The chromaticities of the primary colors and the white
+reference are:</para>
<table frame="none">
<title>sRGB Chromaticities</title>
<tgroup cols="3" align="left">
@@ -896,6 +968,7 @@ values before quantization, but this encoding does not do that.</para>
<title>Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title>
<para>The <xref linkend="adobergb" /> standard defines the colorspace used by computer graphics
that use the AdobeRGB colorspace. This is also known as the <xref linkend="oprgb" /> standard.
+The default transfer function is <constant>V4L2_XFER_FUNC_ADOBERGB</constant>.
The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr
quantization is limited range. The chromaticities of the primary colors and the white reference
are:</para>
@@ -967,7 +1040,8 @@ SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para>
<section id="col-bt2020">
<title>Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title>
<para>The <xref linkend="itu2020" /> standard defines the colorspace used by Ultra-high definition
-television (UHDTV). The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>.
+television (UHDTV). The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>.
+The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>.
The default R'G'B' quantization is limited range (!), and so is the default Y'CbCr quantization.
The chromaticities of the primary colors and the white reference are:</para>
<table frame="none">
@@ -1082,8 +1156,10 @@ clamped to the range [-0.5&hellip;0.5]. The Yc'CbcCrc quantization is limited ra
<section id="col-smpte-240m">
<title>Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title>
- <para>The <xref linkend="smpte240m" /> standard was an interim standard used during the early days of HDTV (1988-1998).
-It has been superseded by Rec. 709. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>.
+ <para>The <xref linkend="smpte240m" /> standard was an interim standard used during
+the early days of HDTV (1988-1998). It has been superseded by Rec. 709.
+The default transfer function is <constant>V4L2_XFER_FUNC_SMPTE240M</constant>.
+The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>.
The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the
white reference are:</para>
<table frame="none">
@@ -1156,8 +1232,10 @@ clamped to the range [-0.5&hellip;0.5]. The Y'CbCr quantization is limited range
<section id="col-sysm">
<title>Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title>
<para>This standard defines the colorspace used by NTSC in 1953. In practice this
-colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding
-is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range.
+colorspace is obsolete and SMPTE 170M should be used instead.
+The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>.
+The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>.
+The default Y'CbCr quantization is limited range.
The chromaticities of the primary colors and the white reference are:</para>
<table frame="none">
<title>NTSC 1953 Chromaticities</title>
@@ -1234,8 +1312,10 @@ This transform is identical to one defined in SMPTE 170M/BT.601.</para>
<section id="col-sysbg">
<title>Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title>
<para>The <xref linkend="tech3213" /> standard defines the colorspace used by PAL/SECAM in 1975. In practice this
-colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding
-is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range.
+colorspace is obsolete and SMPTE 170M should be used instead.
+The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>.
+The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>.
+The default Y'CbCr quantization is limited range.
The chromaticities of the primary colors and the white reference are:</para>
<table frame="none">
<title>EBU Tech. 3213 Chromaticities</title>
@@ -1308,7 +1388,8 @@ This transform is identical to one defined in SMPTE 170M/BT.601.</para>
<section id="col-jpeg">
<title>Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title>
<para>This colorspace defines the colorspace used by most (Motion-)JPEG formats. The chromaticities
-of the primary colors and the white reference are identical to sRGB. The Y'CbCr encoding is
+of the primary colors and the white reference are identical to sRGB. The transfer
+function use is <constant>V4L2_XFER_FUNC_SRGB</constant>. The Y'CbCr encoding is
<constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where
Y' is scaled to [0&hellip;255] and Cb/Cr are scaled to [-128&hellip;128] and
then clipped to [-128&hellip;127].</para>
@@ -1429,6 +1510,7 @@ information.</para>
&sub-y12;
&sub-y10b;
&sub-y16;
+ &sub-y16-be;
&sub-uv8;
&sub-yuyv;
&sub-uyvy;
diff --git a/Documentation/DocBook/media/v4l/remote_controllers.xml b/Documentation/DocBook/media/v4l/remote_controllers.xml
index 5124a6c4daa8..b86844e80257 100644
--- a/Documentation/DocBook/media/v4l/remote_controllers.xml
+++ b/Documentation/DocBook/media/v4l/remote_controllers.xml
@@ -284,7 +284,7 @@ different IR's. Due to that, V4L2 API now specifies a standard for mapping Media
</tgroup>
</table>
-<para>It should be noticed that, sometimes, there some fundamental missing keys at some cheaper IR's. Due to that, it is recommended to:</para>
+<para>It should be noted that, sometimes, there some fundamental missing keys at some cheaper IR's. Due to that, it is recommended to:</para>
<table pgwide="1" frame="none" id="rc_keymap_notes">
<title>Notes</title>
diff --git a/Documentation/DocBook/media/v4l/subdev-formats.xml b/Documentation/DocBook/media/v4l/subdev-formats.xml
index 2588ad781242..4e73345e3eab 100644
--- a/Documentation/DocBook/media/v4l/subdev-formats.xml
+++ b/Documentation/DocBook/media/v4l/subdev-formats.xml
@@ -50,8 +50,16 @@ capture streams and by the application for output streams,
see <xref linkend="colorspaces" />.</entry>
</row>
<row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[6]</entry>
+ <entry>&v4l2-xfer-func;</entry>
+ <entry><structfield>xfer_func</structfield></entry>
+ <entry>This information supplements the
+<structfield>colorspace</structfield> and must be set by the driver for
+capture streams and by the application for output streams,
+see <xref linkend="colorspaces" />.</entry>
+ </row>
+ <row>
+ <entry>__u16</entry>
+ <entry><structfield>reserved</structfield>[11]</entry>
<entry>Reserved for future extensions. Applications and drivers must
set the array to zero.</entry>
</row>
diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
index 9b700a5f4df7..8ffe74f84af1 100644
--- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
@@ -134,7 +134,8 @@ information.</para>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[8]</entry>
- <entry>A place holder for future extensions.</entry>
+ <entry>A place holder for future extensions. Drivers and applications
+must set the array to zero.</entry>
</row>
</tbody>
</tgroup>
diff --git a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml
index 9215627b04c7..73eb5cfe698a 100644
--- a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml
@@ -197,7 +197,17 @@ be muted when playing back at a non-standard speed.
this command does nothing. This command has two flags:
if <constant>V4L2_DEC_CMD_STOP_TO_BLACK</constant> is set, then the decoder will
set the picture to black after it stopped decoding. Otherwise the last image will
-repeat. If <constant>V4L2_DEC_CMD_STOP_IMMEDIATELY</constant> is set, then the decoder
+repeat. mem2mem decoders will stop producing new frames altogether. They will send
+a <constant>V4L2_EVENT_EOS</constant> event when the last frame has been decoded
+and all frames are ready to be dequeued and will set the
+<constant>V4L2_BUF_FLAG_LAST</constant> buffer flag on the last buffer of the
+capture queue to indicate there will be no new buffers produced to dequeue. This
+buffer may be empty, indicated by the driver setting the
+<structfield>bytesused</structfield> field to 0. Once the
+<constant>V4L2_BUF_FLAG_LAST</constant> flag was set, the
+<link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl will not block anymore,
+but return an &EPIPE;.
+If <constant>V4L2_DEC_CMD_STOP_IMMEDIATELY</constant> is set, then the decoder
stops immediately (ignoring the <structfield>pts</structfield> value), otherwise it
will keep decoding until timestamp >= pts or until the last of the pending data from
its internal buffers was decoded.
diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
index 50ccd33948c1..c9c3c7713832 100644
--- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
@@ -133,7 +133,10 @@
<entry>struct timespec</entry>
<entry><structfield>timestamp</structfield></entry>
<entry></entry>
- <entry>Event timestamp.</entry>
+ <entry>Event timestamp. The timestamp has been taken from the
+ <constant>CLOCK_MONOTONIC</constant> clock. To access the
+ same clock outside V4L2, use <function>clock_gettime(2)</function>.
+ </entry>
</row>
<row>
<entry>u32</entry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml
index 0619ca5d2d36..fc1d4625a78c 100644
--- a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml
@@ -129,7 +129,15 @@ this command.</entry>
encoding will continue until the end of the current <wordasword>Group
Of Pictures</wordasword>, otherwise encoding will stop immediately.
When the encoder is already stopped, this command does
-nothing.</entry>
+nothing. mem2mem encoders will send a <constant>V4L2_EVENT_EOS</constant> event
+when the last frame has been decoded and all frames are ready to be dequeued and
+will set the <constant>V4L2_BUF_FLAG_LAST</constant> buffer flag on the last
+buffer of the capture queue to indicate there will be no new buffers produced to
+dequeue. This buffer may be empty, indicated by the driver setting the
+<structfield>bytesused</structfield> field to 0. Once the
+<constant>V4L2_BUF_FLAG_LAST</constant> flag was set, the
+<link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl will not block anymore,
+but return an &EPIPE;.</entry>
</row>
<row>
<entry><constant>V4L2_ENC_CMD_PAUSE</constant></entry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml b/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml
index 5fd72c4c33e3..7c839ab0afbb 100644
--- a/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml
@@ -217,7 +217,8 @@ enumerated.</entry>
<entry>__u32</entry>
<entry><structfield>reserved[2]</structfield></entry>
<entry></entry>
- <entry>Reserved space for future use.</entry>
+ <entry>Reserved space for future use. Must be zeroed by drivers and
+ applications.</entry>
</row>
</tbody>
</tgroup>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml b/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml
index a78454b5abcd..9ed68ac8f474 100644
--- a/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml
@@ -223,7 +223,8 @@ application should zero out all members except for the
<entry>__u32</entry>
<entry><structfield>reserved[2]</structfield></entry>
<entry></entry>
- <entry>Reserved space for future use.</entry>
+ <entry>Reserved space for future use. Must be zeroed by drivers and
+ applications.</entry>
</row>
</tbody>
</tgroup>
diff --git a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml
index 4165e7bfa4ff..a78c9207422f 100644
--- a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml
@@ -184,7 +184,8 @@ of open() for more details.</entry>
<row>
<entry>__u32</entry>
<entry><structfield>reserved[11]</structfield></entry>
- <entry>Reserved field for future use. Must be set to zero.</entry>
+ <entry>Reserved field for future use. Drivers and applications must
+set the array to zero.</entry>
</row>
</tbody>
</tgroup>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
index 764b635ed4cf..06952d7cc770 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
@@ -7,6 +7,8 @@
<refnamediv>
<refname>VIDIOC_G_DV_TIMINGS</refname>
<refname>VIDIOC_S_DV_TIMINGS</refname>
+ <refname>VIDIOC_SUBDEV_G_DV_TIMINGS</refname>
+ <refname>VIDIOC_SUBDEV_S_DV_TIMINGS</refname>
<refpurpose>Get or set DV timings for input or output</refpurpose>
</refnamediv>
@@ -34,7 +36,7 @@
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
- <para>VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS</para>
+ <para>VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS, VIDIOC_SUBDEV_G_DV_TIMINGS, VIDIOC_SUBDEV_S_DV_TIMINGS</para>
</listitem>
</varlistentry>
<varlistentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-edid.xml b/Documentation/DocBook/media/v4l/vidioc-g-edid.xml
index 6df40db4c8ba..2702536bbc7c 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-edid.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-edid.xml
@@ -7,6 +7,8 @@
<refnamediv>
<refname>VIDIOC_G_EDID</refname>
<refname>VIDIOC_S_EDID</refname>
+ <refname>VIDIOC_SUBDEV_G_EDID</refname>
+ <refname>VIDIOC_SUBDEV_S_EDID</refname>
<refpurpose>Get or set the EDID of a video receiver/transmitter</refpurpose>
</refnamediv>
@@ -42,7 +44,7 @@
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
- <para>VIDIOC_G_EDID, VIDIOC_S_EDID</para>
+ <para>VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -82,6 +84,13 @@
<para>If blocks have to be retrieved from the sink, then this call will block until they
have been read.</para>
+ <para>If <structfield>start_block</structfield> and <structfield>blocks</structfield> are
+ both set to 0 when <constant>VIDIOC_G_EDID</constant> is called, then the driver will
+ set <structfield>blocks</structfield> to the total number of available EDID blocks
+ and it will return 0 without copying any data. This is an easy way to discover how many
+ EDID blocks there are. Note that if there are no EDID blocks available at all, then
+ the driver will set <structfield>blocks</structfield> to 0 and it returns 0.</para>
+
<para>To set the EDID blocks of a receiver the application has to fill in the <structfield>pad</structfield>,
<structfield>blocks</structfield> and <structfield>edid</structfield> fields and set
<structfield>start_block</structfield> to 0. It is not possible to set part of an EDID,
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
index 0bb5c060db27..7865351688da 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
@@ -199,7 +199,7 @@ exist no rectangle</emphasis> that satisfies the constraints.</para>
<row>
<entry>__u32</entry>
<entry><structfield>reserved[9]</structfield></entry>
- <entry>Reserved fields for future use.</entry>
+ <entry>Reserved fields for future use. Drivers and applications must zero this array.</entry>
</row>
</tbody>
</tgroup>
diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
index 3504a7f2f382..8b98a0e421fc 100644
--- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
@@ -187,6 +187,16 @@ continue streaming.
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><errorcode>EPIPE</errorcode></term>
+ <listitem>
+ <para><constant>VIDIOC_DQBUF</constant> returns this on an empty
+capture queue for mem2mem codecs if a buffer with the
+<constant>V4L2_BUF_FLAG_LAST</constant> was already dequeued and no new buffers
+are expected to become available.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml
index e185f149e0a1..e9c70a8f3476 100644
--- a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml
@@ -6,6 +6,7 @@
<refnamediv>
<refname>VIDIOC_QUERY_DV_TIMINGS</refname>
+ <refname>VIDIOC_SUBDEV_QUERY_DV_TIMINGS</refname>
<refpurpose>Sense the DV preset received by the current
input</refpurpose>
</refnamediv>
@@ -34,7 +35,7 @@ input</refpurpose>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
- <para>VIDIOC_QUERY_DV_TIMINGS</para>
+ <para>VIDIOC_QUERY_DV_TIMINGS, VIDIOC_SUBDEV_QUERY_DV_TIMINGS</para>
</listitem>
</varlistentry>
<varlistentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-querybuf.xml b/Documentation/DocBook/media/v4l/vidioc-querybuf.xml
index a597155c052d..50bfcb5e8508 100644
--- a/Documentation/DocBook/media/v4l/vidioc-querybuf.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-querybuf.xml
@@ -60,7 +60,8 @@ buffer at any time after buffers have been allocated with the
field. Valid index numbers range from zero
to the number of buffers allocated with &VIDIOC-REQBUFS;
(&v4l2-requestbuffers; <structfield>count</structfield>) minus one.
-The <structfield>reserved</structfield> field should to set to 0.
+The <structfield>reserved</structfield> and <structfield>reserved2 </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 an
array of &v4l2-plane; and the <structfield>length</structfield> field has
diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml
index 78a06a9a5ece..0f193fda0470 100644
--- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml
@@ -112,8 +112,8 @@ as the &v4l2-format; <structfield>type</structfield> field. See <xref
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[2]</entry>
- <entry>A place holder for future extensions. This array should
-be zeroed by applications.</entry>
+ <entry>A place holder for future extensions. Drivers and applications
+must set the array to zero.</entry>
</row>
</tbody>
</tgroup>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
index d0332f610929..5fd0ee78f880 100644
--- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
@@ -5,7 +5,8 @@
</refmeta>
<refnamediv>
- <refname>VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refname>
+ <refname>VIDIOC_SUBSCRIBE_EVENT</refname>
+ <refname>VIDIOC_UNSUBSCRIBE_EVENT</refname>
<refpurpose>Subscribe or unsubscribe event</refpurpose>
</refnamediv>