summaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
blob: 2bbeea9f3e18c80ad8206b1bfed3d37705188c78 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
<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 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>

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