mirror of https://gitee.com/openkylin/linux.git
217 lines
7.1 KiB
XML
217 lines
7.1 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>&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>&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>
|
|
<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">
|
|
&cs-str;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>&media-pad-desc;</entry>
|
|
<entry><structfield>source</structfield></entry>
|
|
<entry>Pad at the origin of this link.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>&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>
|