diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l')
| -rw-r--r-- | Documentation/DocBook/media/v4l/capture.c.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/compat.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/io.xml | 10 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/media-controller.xml | 44 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml | 104 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/media-ioc-enum-links.xml | 56 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/media-ioc-g-topology.xml | 394 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/media-types.xml | 240 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/v4l2.xml | 10 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-create-bufs.xml | 30 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-enumstd.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml | 28 |
14 files changed, 725 insertions, 201 deletions
diff --git a/Documentation/DocBook/media/v4l/capture.c.xml b/Documentation/DocBook/media/v4l/capture.c.xml index 1c5c49a2de59..22126a991b34 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 5701a08ed792..5399e8904715 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 da654031ef3f..144158b3a5ac 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 873ac3a621f0..5f2fc07a93d7 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 5872f8bbf774..0c4f96bfc2de 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 74fb394ec667..2bbeea9f3e18 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 000000000000..63152ab9efba --- /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 000000000000..1af384250910 --- /dev/null +++ b/Documentation/DocBook/media/v4l/media-types.xml @@ -0,0 +1,240 @@ +<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_CONN_TEST</constant></entry> + <entry>Connector for a test generator.</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 7e61643358de..42e626d6c936 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 8ffe74f84af1..d81fa0d4016b 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 4c4603c135fe..f14a3bb1afaa 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 3d038e75d12b..5877f68a5820 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 8065099401d1..f18454e91752 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 842536aae8b4..eb82f7e7d06b 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 |