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/capture.c.xml2
-rw-r--r--Documentation/DocBook/media/v4l/compat.xml2
-rw-r--r--Documentation/DocBook/media/v4l/io.xml10
-rw-r--r--Documentation/DocBook/media/v4l/media-controller.xml44
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml104
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-enum-links.xml56
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-g-topology.xml394
-rw-r--r--Documentation/DocBook/media/v4l/media-types.xml236
-rw-r--r--Documentation/DocBook/media/v4l/v4l2.xml10
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-create-bufs.xml30
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml2
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml2
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumstd.xml2
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml28
14 files changed, 721 insertions, 201 deletions
diff --git a/Documentation/DocBook/media/v4l/capture.c.xml b/Documentation/DocBook/media/v4l/capture.c.xml
index 1c5c49a2d..22126a991 100644
--- a/Documentation/DocBook/media/v4l/capture.c.xml
+++ b/Documentation/DocBook/media/v4l/capture.c.xml
@@ -5,7 +5,7 @@
* This program can be used and distributed without restrictions.
*
* This program is provided with the V4L2 API
- * see http://linuxtv.org/docs.php for more information
+ * see https://linuxtv.org/docs.php for more information
*/
#include <stdio.h>
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
index 5701a08ed..5399e8904 100644
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2666,7 +2666,7 @@ is useful to display images captured with V4L2 devices.</para>
<para>V4L2 does not support digital terrestrial, cable or
satellite broadcast. A separate project aiming at digital receivers
exists. You can find its homepage at <ulink
-url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API
+url="https://linuxtv.org">https://linuxtv.org</ulink>. The Linux DVB API
has no connection to the V4L2 API except that drivers for hybrid
hardware may support both.</para>
</section>
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
index da654031e..144158b3a 100644
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -699,7 +699,7 @@ linkend="v4l2-buf-type" /></entry>
buffer. It depends on the negotiated data format and may change with
each buffer for compressed variable size data like JPEG images.
Drivers must set this field when <structfield>type</structfield>
-refers to an input stream, applications when it refers to an output stream.
+refers to a capture stream, applications when it refers to an output stream.
If the application sets this to 0 for an output stream, then
<structfield>bytesused</structfield> will be set to the size of the
buffer (see the <structfield>length</structfield> field of this struct) by
@@ -720,14 +720,14 @@ linkend="buffer-flags" />.</entry>
<entry>Indicates the field order of the image in the
buffer, see <xref linkend="v4l2-field" />. This field is not used when
the buffer contains VBI data. Drivers must set it when
-<structfield>type</structfield> refers to an input stream,
+<structfield>type</structfield> refers to a capture stream,
applications when it refers to an output stream.</entry>
</row>
<row>
<entry>struct timeval</entry>
<entry><structfield>timestamp</structfield></entry>
<entry></entry>
- <entry><para>For input streams this is time when the first data
+ <entry><para>For capture streams this is time when the first data
byte was captured, as returned by the
<function>clock_gettime()</function> function for the relevant
clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in
@@ -866,7 +866,7 @@ must set this to 0.</entry>
<entry></entry>
<entry>The number of bytes occupied by data in the plane
(its payload). Drivers must set this field when <structfield>type</structfield>
- refers to an input stream, applications when it refers to an output stream.
+ refers to a capture stream, applications when it refers to an output stream.
If the application sets this to 0 for an output stream, then
<structfield>bytesused</structfield> will be set to the size of the
plane (see the <structfield>length</structfield> field of this struct)
@@ -919,7 +919,7 @@ must set this to 0.</entry>
<entry></entry>
<entry>Offset in bytes to video data in the plane.
Drivers must set this field when <structfield>type</structfield>
- refers to an input stream, applications when it refers to an output stream.
+ refers to a capture stream, applications when it refers to an output stream.
Note that data_offset is included in <structfield>bytesused</structfield>.
So the size of the image in the plane is
<structfield>bytesused</structfield>-<structfield>data_offset</structfield> at
diff --git a/Documentation/DocBook/media/v4l/media-controller.xml b/Documentation/DocBook/media/v4l/media-controller.xml
index 873ac3a62..5f2fc07a9 100644
--- a/Documentation/DocBook/media/v4l/media-controller.xml
+++ b/Documentation/DocBook/media/v4l/media-controller.xml
@@ -58,21 +58,36 @@
<title>Media device model</title>
<para>Discovering a device internal topology, and configuring it at runtime,
is one of the goals of the media controller API. To achieve this, hardware
- devices are modelled as an oriented graph of building blocks called entities
- connected through pads.</para>
- <para>An entity is a basic media hardware or software building block. It can
- correspond to a large variety of logical blocks such as physical hardware
- devices (CMOS sensor for instance), logical hardware devices (a building
- block in a System-on-Chip image processing pipeline), DMA channels or
- physical connectors.</para>
- <para>A pad is a connection endpoint through which an entity can interact
- with other entities. Data (not restricted to video) produced by an entity
- flows from the entity's output to one or more entity inputs. Pads should not
- be confused with physical pins at chip boundaries.</para>
- <para>A link is a point-to-point oriented connection between two pads,
- either on the same entity or on different entities. Data flows from a source
- pad to a sink pad.</para>
+ devices and Linux Kernel interfaces are modelled as graph objects on
+ an oriented graph. The object types that constitute the graph are:</para>
+ <itemizedlist>
+ <listitem><para>An <emphasis role="bold">entity</emphasis>
+ is a basic media hardware or software building block. It can correspond to
+ a large variety of logical blocks such as physical hardware devices
+ (CMOS sensor for instance), logical hardware devices (a building block in
+ a System-on-Chip image processing pipeline), DMA channels or physical
+ connectors.</para></listitem>
+ <listitem><para>An <emphasis role="bold">interface</emphasis>
+ is a graph representation of a Linux Kernel userspace API interface,
+ like a device node or a sysfs file that controls one or more entities
+ in the graph.</para></listitem>
+ <listitem><para>A <emphasis role="bold">pad</emphasis>
+ is a data connection endpoint through which an entity can interact with
+ other entities. Data (not restricted to video) produced by an entity
+ flows from the entity's output to one or more entity inputs. Pads should
+ not be confused with physical pins at chip boundaries.</para></listitem>
+ <listitem><para>A <emphasis role="bold">data link</emphasis>
+ is a point-to-point oriented connection between two pads, either on the
+ same entity or on different entities. Data flows from a source pad to a
+ sink pad.</para></listitem>
+ <listitem><para>An <emphasis role="bold">interface link</emphasis>
+ is a point-to-point bidirectional control connection between a Linux
+ Kernel interface and an entity.m</para></listitem>
+ </itemizedlist>
</section>
+
+ <!-- All non-ioctl specific data types go here. -->
+ &sub-media-types;
</chapter>
<appendix id="media-user-func">
@@ -83,6 +98,7 @@
&sub-media-func-ioctl;
<!-- All ioctls go here. -->
&sub-media-ioc-device-info;
+ &sub-media-ioc-g-topology;
&sub-media-ioc-enum-entities;
&sub-media-ioc-enum-links;
&sub-media-ioc-setup-link;
diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml
index 5872f8bbf..0c4f96bfc 100644
--- a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml
+++ b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml
@@ -59,15 +59,6 @@
<para>Entity IDs can be non-contiguous. Applications must
<emphasis>not</emphasis> try to enumerate entities by calling
MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para>
- <para>Two or more entities that share a common non-zero
- <structfield>group_id</structfield> value are considered as logically
- grouped. Groups are used to report
- <itemizedlist>
- <listitem><para>ALSA, VBI and video nodes that carry the same media
- stream</para></listitem>
- <listitem><para>lens and flash controllers associated with a sensor</para></listitem>
- </itemizedlist>
- </para>
<table pgwide="1" frame="none" id="media-entity-desc">
<title>struct <structname>media_entity_desc</structname></title>
@@ -106,7 +97,7 @@
<entry><structfield>revision</structfield></entry>
<entry></entry>
<entry></entry>
- <entry>Entity revision in a driver/hardware specific format.</entry>
+ <entry>Entity revision. Always zero (obsolete)</entry>
</row>
<row>
<entry>__u32</entry>
@@ -120,7 +111,7 @@
<entry><structfield>group_id</structfield></entry>
<entry></entry>
<entry></entry>
- <entry>Entity group ID</entry>
+ <entry>Entity group ID. Always zero (obsolete)</entry>
</row>
<row>
<entry>__u16</entry>
@@ -171,97 +162,6 @@
</tbody>
</tgroup>
</table>
-
- <table frame="none" pgwide="1" id="media-entity-type">
- <title>Media entity types</title>
- <tgroup cols="2">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
- <tbody valign="top">
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE</constant></entry>
- <entry>Unknown device node</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_V4L</constant></entry>
- <entry>V4L video, radio or vbi device node</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_FB</constant></entry>
- <entry>Frame buffer device node</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_ALSA</constant></entry>
- <entry>ALSA card</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_FE</constant></entry>
- <entry>DVB frontend devnode</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_DEMUX</constant></entry>
- <entry>DVB demux devnode</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_DVR</constant></entry>
- <entry>DVB DVR devnode</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_CA</constant></entry>
- <entry>DVB CAM devnode</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_NET</constant></entry>
- <entry>DVB network devnode</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV</constant></entry>
- <entry>Unknown V4L sub-device</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_SENSOR</constant></entry>
- <entry>Video sensor</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_FLASH</constant></entry>
- <entry>Flash controller</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_LENS</constant></entry>
- <entry>Lens controller</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_DECODER</constant></entry>
- <entry>Video decoder, the basic function of the video decoder is to
- accept analogue video from a wide variety of sources such as
- broadcast, DVD players, cameras and video cassette recorders, in
- either NTSC, PAL or HD format and still occasionally SECAM, separate
- it into its component parts, luminance and chrominance, and output
- it in some digital video standard, with appropriate embedded timing
- signals.</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_TUNER</constant></entry>
- <entry>TV and/or radio tuner</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="media-entity-flag">
- <title>Media entity flags</title>
- <tgroup cols="2">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
- <tbody valign="top">
- <row>
- <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry>
- <entry>Default entity for its type. Used to discover the default
- audio, VBI and video devices, the default camera sensor, ...</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
</refsect1>
<refsect1>
diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
index 74fb394ec..2bbeea9f3 100644
--- a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
+++ b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
@@ -118,35 +118,6 @@
</tgroup>
</table>
- <table frame="none" pgwide="1" id="media-pad-flag">
- <title>Media pad flags</title>
- <tgroup cols="2">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
- <tbody valign="top">
- <row>
- <entry><constant>MEDIA_PAD_FL_SINK</constant></entry>
- <entry>Input pad, relative to the entity. Input pads sink data and
- are targets of links.</entry>
- </row>
- <row>
- <entry><constant>MEDIA_PAD_FL_SOURCE</constant></entry>
- <entry>Output pad, relative to the entity. Output pads source data
- and are origins of links.</entry>
- </row>
- <row>
- <entry><constant>MEDIA_PAD_FL_MUST_CONNECT</constant></entry>
- <entry>If this flag is set and the pad is linked to any other
- pad, then at least one of those links must be enabled for the
- entity to be able to stream. There could be temporary reasons
- (e.g. device configuration dependent) for the pad to need
- enabled links even when this flag isn't set; the absence of the
- flag doesn't imply there is none.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
<table pgwide="1" frame="none" id="media-link-desc">
<title>struct <structname>media_link_desc</structname></title>
<tgroup cols="3">
@@ -171,33 +142,6 @@
</tgroup>
</table>
- <table frame="none" pgwide="1" id="media-link-flag">
- <title>Media link flags</title>
- <tgroup cols="2">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
- <tbody valign="top">
- <row>
- <entry><constant>MEDIA_LNK_FL_ENABLED</constant></entry>
- <entry>The link is enabled and can be used to transfer media data.
- When two or more links target a sink pad, only one of them can be
- enabled at a time.</entry>
- </row>
- <row>
- <entry><constant>MEDIA_LNK_FL_IMMUTABLE</constant></entry>
- <entry>The link enabled state can't be modified at runtime. An
- immutable link is always enabled.</entry>
- </row>
- <row>
- <entry><constant>MEDIA_LNK_FL_DYNAMIC</constant></entry>
- <entry>The link enabled state can be modified during streaming. This
- flag is set by drivers and is read-only for applications.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>One and only one of <constant>MEDIA_PAD_FL_SINK</constant> and
- <constant>MEDIA_PAD_FL_SOURCE</constant> must be set for every pad.</para>
</refsect1>
<refsect1>
diff --git a/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml b/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml
new file mode 100644
index 000000000..63152ab9e
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml
@@ -0,0 +1,394 @@
+<refentry id="media-g-topology">
+ <refmeta>
+ <refentrytitle>ioctl MEDIA_IOC_G_TOPOLOGY</refentrytitle>
+ &manvol;
+ </refmeta>
+
+ <refnamediv>
+ <refname>MEDIA_IOC_G_TOPOLOGY</refname>
+ <refpurpose>Enumerate the graph topology and graph element properties</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 media_v2_topology *<parameter>argp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Arguments</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>fd</parameter></term>
+ <listitem>
+ <para>File descriptor returned by
+ <link linkend='media-func-open'><function>open()</function></link>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>request</parameter></term>
+ <listitem>
+ <para>MEDIA_IOC_G_TOPOLOGY</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>argp</parameter></term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><emphasis role="bold">NOTE:</emphasis> This new ioctl is programmed to be added on Kernel 4.6. Its definition/arguments may change until its final version.</para>
+
+ <para>The typical usage of this ioctl is to call it twice.
+ On the first call, the structure defined at &media-v2-topology; should
+ be zeroed. At return, if no errors happen, this ioctl will return the
+ <constant>topology_version</constant> and the total number of entities,
+ interfaces, pads and links.</para>
+ <para>Before the second call, the userspace should allocate arrays to
+ store the graph elements that are desired, putting the pointers to them
+ at the ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping
+ the other values untouched.</para>
+ <para>If the <constant>topology_version</constant> remains the same, the
+ ioctl should fill the desired arrays with the media graph elements.</para>
+
+ <table pgwide="1" frame="none" id="media-v2-topology">
+ <title>struct <structname>media_v2_topology</structname></title>
+ <tgroup cols="5">
+ <colspec colname="c1" />
+ <colspec colname="c2" />
+ <colspec colname="c3" />
+ <colspec colname="c4" />
+ <colspec colname="c5" />
+ <tbody valign="top">
+ <row>
+ <entry>__u64</entry>
+ <entry><structfield>topology_version</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Version of the media graph topology. When the graph is
+ created, this field starts with zero. Every time a graph
+ element is added or removed, this field is
+ incremented.</entry>
+ </row>
+ <row>
+ <entry>__u64</entry>
+ <entry><structfield>num_entities</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Number of entities in the graph</entry>
+ </row>
+ <row>
+ <entry>__u64</entry>
+ <entry><structfield>ptr_entities</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>A pointer to a memory area where the entities array
+ will be stored, converted to a 64-bits integer.
+ It can be zero. if zero, the ioctl won't store the
+ entities. It will just update
+ <constant>num_entities</constant></entry>
+ </row>
+ <row>
+ <entry>__u64</entry>
+ <entry><structfield>num_interfaces</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Number of interfaces in the graph</entry>
+ </row>
+ <row>
+ <entry>__u64</entry>
+ <entry><structfield>ptr_interfaces</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>A pointer to a memory area where the interfaces array
+ will be stored, converted to a 64-bits integer.
+ It can be zero. if zero, the ioctl won't store the
+ interfaces. It will just update
+ <constant>num_interfaces</constant></entry>
+ </row>
+ <row>
+ <entry>__u64</entry>
+ <entry><structfield>num_pads</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Total number of pads in the graph</entry>
+ </row>
+ <row>
+ <entry>__u64</entry>
+ <entry><structfield>ptr_pads</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>A pointer to a memory area where the pads array
+ will be stored, converted to a 64-bits integer.
+ It can be zero. if zero, the ioctl won't store the
+ pads. It will just update
+ <constant>num_pads</constant></entry>
+ </row>
+ <row>
+ <entry>__u64</entry>
+ <entry><structfield>num_links</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Total number of data and interface links in the graph</entry>
+ </row>
+ <row>
+ <entry>__u64</entry>
+ <entry><structfield>ptr_links</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>A pointer to a memory area where the links array
+ will be stored, converted to a 64-bits integer.
+ It can be zero. if zero, the ioctl won't store the
+ links. It will just update
+ <constant>num_links</constant></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1" frame="none" id="media-v2-entity">
+ <title>struct <structname>media_v2_entity</structname></title>
+ <tgroup cols="5">
+ <colspec colname="c1" />
+ <colspec colname="c2" />
+ <colspec colname="c3" />
+ <colspec colname="c4" />
+ <colspec colname="c5" />
+ <tbody valign="top">
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>id</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Unique ID for the entity.</entry>
+ </row>
+ <row>
+ <entry>char</entry>
+ <entry><structfield>name</structfield>[64]</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Entity name as an UTF-8 NULL-terminated string.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>function</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Entity main function, see <xref linkend="media-entity-type" /> for details.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>reserved</structfield>[12]</entry>
+ <entry>Reserved for future extensions. Drivers and applications must
+ set this array to zero.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1" frame="none" id="media-v2-interface">
+ <title>struct <structname>media_v2_interface</structname></title>
+ <tgroup cols="5">
+ <colspec colname="c1" />
+ <colspec colname="c2" />
+ <colspec colname="c3" />
+ <colspec colname="c4" />
+ <colspec colname="c5" />
+ <tbody valign="top">
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>id</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Unique ID for the interface.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>intf_type</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Interface type, see <xref linkend="media-intf-type" /> for details.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>flags</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Interface flags. Currently unused.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>reserved</structfield>[9]</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Reserved for future extensions. Drivers and applications must
+ set this array to zero.</entry>
+ </row>
+ <row>
+ <entry>struct media_v2_intf_devnode</entry>
+ <entry><structfield>devnode</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Used only for device node interfaces. See <xref linkend="media-v2-intf-devnode" /> for details..</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1" frame="none" id="media-v2-intf-devnode">
+ <title>struct <structname>media_v2_interface</structname></title>
+ <tgroup cols="5">
+ <colspec colname="c1" />
+ <colspec colname="c2" />
+ <colspec colname="c3" />
+ <colspec colname="c4" />
+ <colspec colname="c5" />
+ <tbody valign="top">
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>major</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Device node major number.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>minor</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Device node minor number.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1" frame="none" id="media-v2-pad">
+ <title>struct <structname>media_v2_pad</structname></title>
+ <tgroup cols="5">
+ <colspec colname="c1" />
+ <colspec colname="c2" />
+ <colspec colname="c3" />
+ <colspec colname="c4" />
+ <colspec colname="c5" />
+ <tbody valign="top">
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>id</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Unique ID for the pad.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>entity_id</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Unique ID for the entity where this pad belongs.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>flags</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Pad flags, see <xref linkend="media-pad-flag" /> for more details.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>reserved</structfield>[9]</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Reserved for future extensions. Drivers and applications must
+ set this array to zero.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1" frame="none" id="media-v2-link">
+ <title>struct <structname>media_v2_pad</structname></title>
+ <tgroup cols="5">
+ <colspec colname="c1" />
+ <colspec colname="c2" />
+ <colspec colname="c3" />
+ <colspec colname="c4" />
+ <colspec colname="c5" />
+ <tbody valign="top">
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>id</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Unique ID for the pad.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>source_id</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ <para>On pad to pad links: unique ID for the source pad.</para>
+ <para>On interface to entity links: unique ID for the interface.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>sink_id</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ <para>On pad to pad links: unique ID for the sink pad.</para>
+ <para>On interface to entity links: unique ID for the entity.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>flags</structfield></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>reserved</structfield>[5]</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>Reserved for future extensions. Drivers and applications must
+ set this array to zero.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </refsect1>
+
+ <refsect1>
+ &return-value;
+
+ <variablelist>
+ <varlistentry>
+ <term><errorcode>ENOSPC</errorcode></term>
+ <listitem>
+ <para>This is returned when either one or more of the num_entities,
+ num_interfaces, num_links or num_pads are non-zero and are smaller
+ than the actual number of elements inside the graph. This may happen
+ if the <constant>topology_version</constant> changed when compared
+ to the last time this ioctl was called. Userspace should usually
+ free the area for the pointers, zero the struct elements and call
+ this ioctl again.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+</refentry>
diff --git a/Documentation/DocBook/media/v4l/media-types.xml b/Documentation/DocBook/media/v4l/media-types.xml
new file mode 100644
index 000000000..0ee0f3386
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/media-types.xml
@@ -0,0 +1,236 @@
+<section id="media-controller-types">
+<title>Types and flags used to represent the media graph elements</title>
+
+ <table frame="none" pgwide="1" id="media-entity-type">
+ <title>Media entity types</title>
+ <tgroup cols="2">
+ <colspec colname="c1"/>
+ <colspec colname="c2"/>
+ <tbody valign="top">
+ <row>
+ <entry><constant>MEDIA_ENT_F_UNKNOWN</constant> and <constant>MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN</constant></entry>
+ <entry>Unknown entity. That generally indicates that
+ a driver didn't initialize properly the entity, with is a Kernel bug</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_IO_V4L</constant></entry>
+ <entry>Data streaming input and/or output entity.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_IO_VBI</constant></entry>
+ <entry>V4L VBI streaming input or output entity</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_IO_SWRADIO</constant></entry>
+ <entry>V4L Software Digital Radio (SDR) streaming input or output entity</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_IO_DTV</constant></entry>
+ <entry>DVB Digital TV streaming input or output entity</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_DTV_DEMOD</constant></entry>
+ <entry>Digital TV demodulator entity.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_TS_DEMUX</constant></entry>
+ <entry>MPEG Transport stream demux entity. Could be implemented on hardware or in Kernelspace by the Linux DVB subsystem.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_DTV_CA</constant></entry>
+ <entry>Digital TV Conditional Access module (CAM) entity</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_DTV_NET_DECAP</constant></entry>
+ <entry>Digital TV network ULE/MLE desencapsulation entity. Could be implemented on hardware or in Kernelspace</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_CONN_RF</constant></entry>
+ <entry>Connector for a Radio Frequency (RF) signal.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_CONN_SVIDEO</constant></entry>
+ <entry>Connector for a S-Video signal.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_CONN_COMPOSITE</constant></entry>
+ <entry>Connector for a RGB composite signal.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_CAM_SENSOR</constant></entry>
+ <entry>Camera video sensor entity.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_FLASH</constant></entry>
+ <entry>Flash controller entity.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_LENS</constant></entry>
+ <entry>Lens controller entity.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_ATV_DECODER</constant></entry>
+ <entry>Analog video decoder, the basic function of the video decoder
+ is to accept analogue video from a wide variety of sources such as
+ broadcast, DVD players, cameras and video cassette recorders, in
+ either NTSC, PAL, SECAM or HD format, separating the stream
+ into its component parts, luminance and chrominance, and output
+ it in some digital video standard, with appropriate timing
+ signals.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_F_TUNER</constant></entry>
+ <entry>Digital TV, analog TV, radio and/or software radio tuner.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table frame="none" pgwide="1" id="media-entity-flag">
+ <title>Media entity flags</title>
+ <tgroup cols="2">
+ <colspec colname="c1"/>
+ <colspec colname="c2"/>
+ <tbody valign="top">
+ <row>
+ <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry>
+ <entry>Default entity for its type. Used to discover the default
+ audio, VBI and video devices, the default camera sensor, ...</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_ENT_FL_CONNECTOR</constant></entry>
+ <entry>The entity represents a data conector</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table frame="none" pgwide="1" id="media-intf-type">
+ <title>Media interface types</title>
+ <tgroup cols="3">
+ <colspec colname="c1"/>
+ <colspec colname="c2"/>
+ <colspec colname="c3"/>
+ <tbody valign="top">
+ <row>
+ <entry><constant>MEDIA_INTF_T_DVB_FE</constant></entry>
+ <entry>Device node interface for the Digital TV frontend</entry>
+ <entry>typically, /dev/dvb/adapter?/frontend?</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_INTF_T_DVB_DEMUX</constant></entry>
+ <entry>Device node interface for the Digital TV demux</entry>
+ <entry>typically, /dev/dvb/adapter?/demux?</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_INTF_T_DVB_DVR</constant></entry>
+ <entry>Device node interface for the Digital TV DVR</entry>
+ <entry>typically, /dev/dvb/adapter?/dvr?</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_INTF_T_DVB_CA</constant></entry>
+ <entry>Device node interface for the Digital TV Conditional Access</entry>
+ <entry>typically, /dev/dvb/adapter?/ca?</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_INTF_T_DVB_FE</constant></entry>
+ <entry>Device node interface for the Digital TV network control</entry>
+ <entry>typically, /dev/dvb/adapter?/net?</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_INTF_T_V4L_VIDEO</constant></entry>
+ <entry>Device node interface for video (V4L)</entry>
+ <entry>typically, /dev/video?</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_INTF_T_V4L_VBI</constant></entry>
+ <entry>Device node interface for VBI (V4L)</entry>
+ <entry>typically, /dev/vbi?</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_INTF_T_V4L_RADIO</constant></entry>
+ <entry>Device node interface for radio (V4L)</entry>
+ <entry>typically, /dev/vbi?</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_INTF_T_V4L_SUBDEV</constant></entry>
+ <entry>Device node interface for a V4L subdevice</entry>
+ <entry>typically, /dev/v4l-subdev?</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_INTF_T_V4L_SWRADIO</constant></entry>
+ <entry>Device node interface for Software Defined Radio (V4L)</entry>
+ <entry>typically, /dev/swradio?</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table frame="none" pgwide="1" id="media-pad-flag">
+ <title>Media pad flags</title>
+ <tgroup cols="2">
+ <colspec colname="c1"/>
+ <colspec colname="c2"/>
+ <tbody valign="top">
+ <row>
+ <entry><constant>MEDIA_PAD_FL_SINK</constant></entry>
+ <entry>Input pad, relative to the entity. Input pads sink data and
+ are targets of links.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_PAD_FL_SOURCE</constant></entry>
+ <entry>Output pad, relative to the entity. Output pads source data
+ and are origins of links.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_PAD_FL_MUST_CONNECT</constant></entry>
+ <entry>If this flag is set and the pad is linked to any other
+ pad, then at least one of those links must be enabled for the
+ entity to be able to stream. There could be temporary reasons
+ (e.g. device configuration dependent) for the pad to need
+ enabled links even when this flag isn't set; the absence of the
+ flag doesn't imply there is none.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>One and only one of <constant>MEDIA_PAD_FL_SINK</constant> and
+ <constant>MEDIA_PAD_FL_SOURCE</constant> must be set for every pad.</para>
+
+ <table frame="none" pgwide="1" id="media-link-flag">
+ <title>Media link flags</title>
+ <tgroup cols="2">
+ <colspec colname="c1"/>
+ <colspec colname="c2"/>
+ <tbody valign="top">
+ <row>
+ <entry><constant>MEDIA_LNK_FL_ENABLED</constant></entry>
+ <entry>The link is enabled and can be used to transfer media data.
+ When two or more links target a sink pad, only one of them can be
+ enabled at a time.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_LNK_FL_IMMUTABLE</constant></entry>
+ <entry>The link enabled state can't be modified at runtime. An
+ immutable link is always enabled.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_LNK_FL_DYNAMIC</constant></entry>
+ <entry>The link enabled state can be modified during streaming. This
+ flag is set by drivers and is read-only for applications.</entry>
+ </row>
+ <row>
+ <entry><constant>MEDIA_LNK_FL_LINK_TYPE</constant></entry>
+ <entry><para>This is a bitmask that defines the type of the link.
+ Currently, two types of links are supported:</para>
+ <para><constant>MEDIA_LNK_FL_DATA_LINK</constant>
+ if the link is between two pads</para>
+ <para><constant>MEDIA_LNK_FL_INTERFACE_LINK</constant>
+ if the link is between an interface and an entity</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+</section>
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index 7e6164335..42e626d6c 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -152,6 +152,16 @@ structs, ioctls) must be noted in more detail in the history chapter
(compat.xml), along with the possible impact on existing drivers and
applications. -->
<revision>
+ <revnumber>4.5</revnumber>
+ <date>2015-10-29</date>
+ <authorinitials>rr</authorinitials>
+ <revremark>Extend vidioc-g-ext-ctrls;. Replace ctrl_class with a new
+union with ctrl_class and which. Which is used to select the current value of
+the control or the default value.
+ </revremark>
+ </revision>
+
+ <revision>
<revnumber>4.4</revnumber>
<date>2015-05-26</date>
<authorinitials>ap</authorinitials>
diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
index 8ffe74f84..d81fa0d40 100644
--- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
@@ -58,7 +58,7 @@
<para>This ioctl is used to create buffers for <link linkend="mmap">memory
mapped</link> or <link linkend="userp">user pointer</link> or <link
linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in
-addition to the <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter
+addition to the &VIDIOC-REQBUFS; ioctl, when a tighter
control over buffers is required. This ioctl can be called multiple times to
create buffers of different sizes.</para>
@@ -71,30 +71,28 @@ zeroed.</para>
<para>The <structfield>format</structfield> field specifies the image format
that the buffers must be able to handle. The application has to fill in this
-&v4l2-format;. Usually this will be done using the
-<constant>VIDIOC_TRY_FMT</constant> or <constant>VIDIOC_G_FMT</constant> ioctl()
-to ensure that the requested format is supported by the driver. Unsupported
-formats will result in an error.</para>
+&v4l2-format;. Usually this will be done using the &VIDIOC-TRY-FMT; or &VIDIOC-G-FMT; ioctls
+to ensure that the requested format is supported by the driver.
+Based on the format's <structfield>type</structfield> field the requested buffer
+size (for single-planar) or plane sizes (for multi-planar formats) will be
+used for the allocated buffers. The driver may return an error if the size(s)
+are not supported by the hardware (usually because they are too small).</para>
<para>The buffers created by this ioctl will have as minimum size the size
-defined by the <structfield>format.pix.sizeimage</structfield> field. If the
+defined by the <structfield>format.pix.sizeimage</structfield> field (or the
+corresponding fields for other format types). Usually if the
<structfield>format.pix.sizeimage</structfield> field is less than the minimum
-required for the given format, then <structfield>sizeimage</structfield> will be
-increased by the driver to that minimum to allocate the buffers. If it is
-larger, then the value will be used as-is. The same applies to the
-<structfield>sizeimage</structfield> field of the
-<structname>v4l2_plane_pix_format</structname> structure in the case of
-multiplanar formats.</para>
+required for the given format, then an error will be returned since drivers will
+typically not allow this. If it is larger, then the value will be used as-is.
+In other words, the driver may reject the requested size, but if it is accepted
+the driver will use it unchanged.</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>
+the number requested.</para>
<table pgwide="1" frame="none" id="v4l2-create-buffers">
<title>struct <structname>v4l2_create_buffers</structname></title>
diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml
index 4c4603c13..f14a3bb1a 100644
--- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml
@@ -99,7 +99,7 @@ if the driver supports writing registers to the device.</para>
<para>We recommended the <application>v4l2-dbg</application>
utility over calling this ioctl directly. It is available from the
LinuxTV v4l-dvb repository; see <ulink
-url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
+url="https://linuxtv.org/repo/">https://linuxtv.org/repo/</ulink> for
access instructions.</para>
<!-- Note for convenience vidioc-dbg-g-register.sgml
diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml
index 3d038e75d..5877f68a5 100644
--- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml
@@ -117,7 +117,7 @@ However when a driver supports these ioctls it must also support
<para>We recommended the <application>v4l2-dbg</application>
utility over calling these ioctls directly. It is available from the
LinuxTV v4l-dvb repository; see <ulink
-url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
+url="https://linuxtv.org/repo/">https://linuxtv.org/repo/</ulink> for
access instructions.</para>
<!-- Note for convenience vidioc-dbg-g-chip-info.sgml
diff --git a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml
index 806509940..f18454e91 100644
--- a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml
@@ -198,7 +198,7 @@ video4linux-list@redhat.com on 17 Oct 2002
<constant>V4L2_STD_ATSC_16_VSB</constant> are U.S. terrestrial digital
TV standards. Presently the V4L2 API does not support digital TV. See
also the Linux DVB API at <ulink
-url="http://linuxtv.org">http://linuxtv.org</ulink>.</para>
+url="https://linuxtv.org">https://linuxtv.org</ulink>.</para>
<para><programlisting>
#define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\
V4L2_STD_PAL_B1 |\
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
index 842536aae..eb82f7e7d 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
@@ -61,7 +61,7 @@ must belong to the same control class.</para>
<para>Applications must always fill in the
<structfield>count</structfield>,
-<structfield>ctrl_class</structfield>,
+<structfield>which</structfield>,
<structfield>controls</structfield> and
<structfield>reserved</structfield> fields of &v4l2-ext-controls;, and
initialize the &v4l2-ext-control; array pointed to by the
@@ -109,7 +109,7 @@ the driver whether wrong values are automatically adjusted to a valid
value or if an error is returned.</para>
<para>When the <structfield>id</structfield> or
-<structfield>ctrl_class</structfield> is invalid drivers return an
+<structfield>which</structfield> is invalid drivers return an
&EINVAL;. When the value is out of bounds drivers can choose to take
the closest valid value or return an &ERANGE;, whatever seems more
appropriate. In the first case the new value is set in
@@ -223,7 +223,12 @@ Valid if <constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set for this control
<tgroup cols="3">
&cs-str;
<tbody valign="top">
+ <row>
+ <entry>union</entry>
+ <entry>(anonymous)</entry>
+ </row>
<row>
+ <entry></entry>
<entry>__u32</entry>
<entry><structfield>ctrl_class</structfield></entry>
<entry>The control class to which all controls belong, see
@@ -235,6 +240,23 @@ with a <structfield>count</structfield> of 0. If that succeeds, then the driver
supports this feature.</entry>
</row>
<row>
+ <entry></entry>
+ <entry>__u32</entry>
+ <entry><structfield>which</structfield></entry>
+ <entry><para>Which value of the control to get/set/try. <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>
+will return the current value of the control and <constant>V4L2_CTRL_WHICH_DEF_VAL</constant> will
+return the default value of the control. Please note that you can only get the default value of the
+control, you cannot set or try it.</para>
+<para>For backwards compatibility you can also use a control class here (see
+<xref linkend="ctrl-class" />). In that case all controls have to belong to that
+control class. This usage is deprecated, instead just use <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>.
+There are some very old drivers that do not yet support <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>
+and that require a control class here. You can test for such drivers by setting ctrl_class to
+<constant>V4L2_CTRL_WHICH_CUR_VAL</constant> and calling VIDIOC_TRY_EXT_CTRLS with a count of 0.
+If that fails, then the driver does not support <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>.</para>
+</entry>
+ </row>
+ <row>
<entry>__u32</entry>
<entry><structfield>count</structfield></entry>
<entry>The number of controls in the controls array. May
@@ -390,7 +412,7 @@ These controls are described in <xref linkend="rf-tuner-controls" />.</entry>
<listitem>
<para>The &v4l2-ext-control; <structfield>id</structfield>
is invalid, the &v4l2-ext-controls;
-<structfield>ctrl_class</structfield> is invalid, or the &v4l2-ext-control;
+<structfield>which</structfield> is invalid, or the &v4l2-ext-control;
<structfield>value</structfield> was inappropriate (e.g. the given menu
index is not supported by the driver). This error code is
also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and