e02188c90f
Drivers often need to associate pipeline objects to entities, and to take stream state into account when configuring entities and links. The pipeline API helps drivers manage that information. When starting streaming, drivers call media_entity_pipeline_start(). The function marks all entities connected to the given entity through enabled links, either directly or indirectly, as streaming. Similarly, when stopping the stream, drivers call media_entity_pipeline_stop(). The media_entity_pipeline_start() function takes a pointer to a media pipeline and stores it in every entity in the graph. Drivers should embed the media_pipeline structure in higher-level pipeline structures and can then access the pipeline through the media_entity structure. Link configuration will fail with -EBUSY by default if either end of the link is a streaming entity, unless the link is marked with the MEDIA_LNK_FL_DYNAMIC flag. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Hans Verkuil <hverkuil@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
208 lines
6.7 KiB
XML
208 lines
6.7 KiB
XML
<refentry id="media-ioc-enum-links">
|
|
<refmeta>
|
|
<refentrytitle>ioctl MEDIA_IOC_ENUM_LINKS</refentrytitle>
|
|
&manvol;
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>MEDIA_IOC_ENUM_LINKS</refname>
|
|
<refpurpose>Enumerate all pads and links for a given entity</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_links_enum *<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_ENUM_LINKS</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>argp</parameter></term>
|
|
<listitem>
|
|
<para></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>To enumerate pads and/or links for a given entity, applications set
|
|
the entity field of a &media-links-enum; structure and initialize the
|
|
&media-pad-desc; and &media-link-desc; structure arrays pointed by the
|
|
<structfield>pads</structfield> and <structfield>links</structfield> fields.
|
|
They then call the MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this
|
|
structure.</para>
|
|
<para>If the <structfield>pads</structfield> field is not NULL, the driver
|
|
fills the <structfield>pads</structfield> array with information about the
|
|
entity's pads. The array must have enough room to store all the entity's
|
|
pads. The number of pads can be retrieved with the &MEDIA-IOC-ENUM-ENTITIES;
|
|
ioctl.</para>
|
|
<para>If the <structfield>links</structfield> field is not NULL, the driver
|
|
fills the <structfield>links</structfield> array with information about the
|
|
entity's outbound links. The array must have enough room to store all the
|
|
entity's outbound links. The number of outbound links can be retrieved with
|
|
the &MEDIA-IOC-ENUM-ENTITIES; ioctl.</para>
|
|
<para>Only forward links that originate at one of the entity's source pads
|
|
are returned during the enumeration process.</para>
|
|
|
|
<table pgwide="1" frame="none" id="media-links-enum">
|
|
<title>struct <structname>media_links_enum</structname></title>
|
|
<tgroup cols="3">
|
|
&cs-str;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>entity</structfield></entry>
|
|
<entry>Entity id, set by the application.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>struct &media-pad-desc;</entry>
|
|
<entry>*<structfield>pads</structfield></entry>
|
|
<entry>Pointer to a pads array allocated by the application. Ignored
|
|
if NULL.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>struct &media-link-desc;</entry>
|
|
<entry>*<structfield>links</structfield></entry>
|
|
<entry>Pointer to a links array allocated by the application. Ignored
|
|
if NULL.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table pgwide="1" frame="none" id="media-pad-desc">
|
|
<title>struct <structname>media_pad_desc</structname></title>
|
|
<tgroup cols="3">
|
|
&cs-str;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>entity</structfield></entry>
|
|
<entry>ID of the entity this pad belongs to.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u16</entry>
|
|
<entry><structfield>index</structfield></entry>
|
|
<entry>0-based pad index.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>flags</structfield></entry>
|
|
<entry>Pad flags, see <xref linkend="media-pad-flag" /> for more details.</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>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table pgwide="1" frame="none" id="media-link-desc">
|
|
<title>struct <structname>media_links_desc</structname></title>
|
|
<tgroup cols="3">
|
|
&cs-str;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>struct &media-pad-desc;</entry>
|
|
<entry><structfield>source</structfield></entry>
|
|
<entry>Pad at the origin of this link.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>struct &media-pad-desc;</entry>
|
|
<entry><structfield>sink</structfield></entry>
|
|
<entry>Pad at the target of this link.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>flags</structfield></entry>
|
|
<entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry>
|
|
</row>
|
|
</tbody>
|
|
</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>
|
|
&return-value;
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><errorcode>EINVAL</errorcode></term>
|
|
<listitem>
|
|
<para>The &media-links-enum; <structfield>id</structfield> references
|
|
a non-existing entity.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
</refentry>
|