Documentation/DocBook/media/v4l/media-ioc-enum-links.xml

   1 <refentry id="media-ioc-enum-links">
   2   <refmeta>
   3     <refentrytitle>ioctl MEDIA_IOC_ENUM_LINKS</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>MEDIA_IOC_ENUM_LINKS</refname>
   9     <refpurpose>Enumerate all pads and links for a given entity</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcprototype>
  15         <funcdef>int <function>ioctl</function></funcdef>
  16         <paramdef>int <parameter>fd</parameter></paramdef>
  17         <paramdef>int <parameter>request</parameter></paramdef>
  18         <paramdef>struct media_links_enum *<parameter>argp</parameter></paramdef>
  19       </funcprototype>
  20     </funcsynopsis>
  21   </refsynopsisdiv>
  22
  23   <refsect1>
  24     <title>Arguments</title>
  25
  26     <variablelist>
  27       <varlistentry>
  28         <term><parameter>fd</parameter></term>
  29         <listitem>
  30           <para>File descriptor returned by
  31           <link linkend='media-func-open'><function>open()</function></link>.</para>
  32         </listitem>
  33       </varlistentry>
  34       <varlistentry>
  35         <term><parameter>request</parameter></term>
  36         <listitem>
  37           <para>MEDIA_IOC_ENUM_LINKS</para>
  38         </listitem>
  39       </varlistentry>
  40       <varlistentry>
  41         <term><parameter>argp</parameter></term>
  42         <listitem>
  43           <para></para>
  44         </listitem>
  45       </varlistentry>
  46     </variablelist>
  47   </refsect1>
  48
  49   <refsect1>
  50     <title>Description</title>
  51
  52     <para>To enumerate pads and/or links for a given entity, applications set
  53     the entity field of a &media-links-enum; structure and initialize the
  54     &media-pad-desc; and &media-link-desc; structure arrays pointed by the
  55     <structfield>pads</structfield> and <structfield>links</structfield> fields.
  56     They then call the MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this
  57     structure.</para>
  58     <para>If the <structfield>pads</structfield> field is not NULL, the driver
  59     fills the <structfield>pads</structfield> array with information about the
  60     entity's pads. The array must have enough room to store all the entity's
  61     pads. The number of pads can be retrieved with the &MEDIA-IOC-ENUM-ENTITIES;
  62     ioctl.</para>
  63     <para>If the <structfield>links</structfield> field is not NULL, the driver
  64     fills the <structfield>links</structfield> array with information about the
  65     entity's outbound links. The array must have enough room to store all the
  66     entity's outbound links. The number of outbound links can be retrieved with
  67     the &MEDIA-IOC-ENUM-ENTITIES; ioctl.</para>
  68     <para>Only forward links that originate at one of the entity's source pads
  69     are returned during the enumeration process.</para>
  70
  71     <table pgwide="1" frame="none" id="media-links-enum">
  72       <title>struct <structname>media_links_enum</structname></title>
  73       <tgroup cols="3">
  74         &cs-str;
  75         <tbody valign="top">
  76           <row>
  77             <entry>__u32</entry>
  78             <entry><structfield>entity</structfield></entry>
  79             <entry>Entity id, set by the application.</entry>
  80           </row>
  81           <row>
  82             <entry>&media-pad-desc;</entry>
  83             <entry>*<structfield>pads</structfield></entry>
  84             <entry>Pointer to a pads array allocated by the application. Ignored
  85             if NULL.</entry>
  86           </row>
  87           <row>
  88             <entry>&media-link-desc;</entry>
  89             <entry>*<structfield>links</structfield></entry>
  90             <entry>Pointer to a links array allocated by the application. Ignored
  91             if NULL.</entry>
  92           </row>
  93         </tbody>
  94       </tgroup>
  95     </table>
  96
  97     <table pgwide="1" frame="none" id="media-pad-desc">
  98       <title>struct <structname>media_pad_desc</structname></title>
  99       <tgroup cols="3">
 100         &cs-str;
 101         <tbody valign="top">
 102           <row>
 103             <entry>__u32</entry>
 104             <entry><structfield>entity</structfield></entry>
 105             <entry>ID of the entity this pad belongs to.</entry>
 106           </row>
 107           <row>
 108             <entry>__u16</entry>
 109             <entry><structfield>index</structfield></entry>
 110             <entry>0-based pad index.</entry>
 111           </row>
 112           <row>
 113             <entry>__u32</entry>
 114             <entry><structfield>flags</structfield></entry>
 115             <entry>Pad flags, see <xref linkend="media-pad-flag" /> for more details.</entry>
 116           </row>
 117         </tbody>
 118       </tgroup>
 119     </table>
 120
 121     <table pgwide="1" frame="none" id="media-link-desc">
 122       <title>struct <structname>media_link_desc</structname></title>
 123       <tgroup cols="3">
 124         &cs-str;
 125         <tbody valign="top">
 126           <row>
 127             <entry>&media-pad-desc;</entry>
 128             <entry><structfield>source</structfield></entry>
 129             <entry>Pad at the origin of this link.</entry>
 130           </row>
 131           <row>
 132             <entry>&media-pad-desc;</entry>
 133             <entry><structfield>sink</structfield></entry>
 134             <entry>Pad at the target of this link.</entry>
 135           </row>
 136           <row>
 137             <entry>__u32</entry>
 138             <entry><structfield>flags</structfield></entry>
 139             <entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry>
 140           </row>
 141         </tbody>
 142       </tgroup>
 143     </table>
 144
 145   </refsect1>
 146
 147   <refsect1>
 148     &return-value;
 149
 150     <variablelist>
 151       <varlistentry>
 152         <term><errorcode>EINVAL</errorcode></term>
 153         <listitem>
 154           <para>The &media-links-enum; <structfield>id</structfield> references
 155           a non-existing entity.</para>
 156         </listitem>
 157       </varlistentry>
 158     </variablelist>
 159   </refsect1>
 160 </refentry>