Documentation/DocBook/media/v4l/media-ioc-enum-links.xml - kernel/bruno - Git at Google

 <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>
	<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>