aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/v4l/media-ioc-enum-links.xml
diff options
context:
space:
mode:
authorLaurent Pinchart <laurent.pinchart@ideasonboard.com>2009-12-09 06:40:01 -0500
committerMauro Carvalho Chehab <mchehab@redhat.com>2011-03-22 03:53:14 -0400
commit1651333b09743887bc2dd3d158a11853a2be3fe7 (patch)
tree965dd31e8fbd0c866bbcd47b86baccc238101ef7 /Documentation/DocBook/v4l/media-ioc-enum-links.xml
parent140d88165c25137e871f9559e67986ed89251105 (diff)
[media] media: Entities, pads and links enumeration
Create the following two ioctls and implement them at the media device level to enumerate entities, pads and links. - MEDIA_IOC_ENUM_ENTITIES: Enumerate entities and their properties - MEDIA_IOC_ENUM_LINKS: Enumerate all pads and links for a given entity Entity IDs can be non-contiguous. Userspace applications should enumerate entities using the MEDIA_ENT_ID_FLAG_NEXT flag. When the flag is set in the entity ID, the MEDIA_IOC_ENUM_ENTITIES will return the next entity with an ID bigger than the requested one. Only forward links that originate at one of the entity's source pads are returned during the enumeration process. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi> Acked-by: Hans Verkuil <hverkuil@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/DocBook/v4l/media-ioc-enum-links.xml')
-rw-r--r--Documentation/DocBook/v4l/media-ioc-enum-links.xml202
1 files changed, 202 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/v4l/media-ioc-enum-links.xml
new file mode 100644
index 000000000000..6da884159cab
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-ioc-enum-links.xml
@@ -0,0 +1,202 @@
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>struct &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>struct &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 frame="none" pgwide="1" id="media-pad-flag">
122 <title>Media pad flags</title>
123 <tgroup cols="2">
124 <colspec colname="c1"/>
125 <colspec colname="c2"/>
126 <tbody valign="top">
127 <row>
128 <entry><constant>MEDIA_PAD_FL_SINK</constant></entry>
129 <entry>Input pad, relative to the entity. Input pads sink data and
130 are targets of links.</entry>
131 </row>
132 <row>
133 <entry><constant>MEDIA_PAD_FL_SOURCE</constant></entry>
134 <entry>Output pad, relative to the entity. Output pads source data
135 and are origins of links.</entry>
136 </row>
137 </tbody>
138 </tgroup>
139 </table>
140
141 <table pgwide="1" frame="none" id="media-link-desc">
142 <title>struct <structname>media_links_desc</structname></title>
143 <tgroup cols="3">
144 &cs-str;
145 <tbody valign="top">
146 <row>
147 <entry>struct &media-pad-desc;</entry>
148 <entry><structfield>source</structfield></entry>
149 <entry>Pad at the origin of this link.</entry>
150 </row>
151 <row>
152 <entry>struct &media-pad-desc;</entry>
153 <entry><structfield>sink</structfield></entry>
154 <entry>Pad at the target of this link.</entry>
155 </row>
156 <row>
157 <entry>__u32</entry>
158 <entry><structfield>flags</structfield></entry>
159 <entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry>
160 </row>
161 </tbody>
162 </tgroup>
163 </table>
164
165 <table frame="none" pgwide="1" id="media-link-flag">
166 <title>Media link flags</title>
167 <tgroup cols="2">
168 <colspec colname="c1"/>
169 <colspec colname="c2"/>
170 <tbody valign="top">
171 <row>
172 <entry><constant>MEDIA_LNK_FL_ENABLED</constant></entry>
173 <entry>The link is enabled and can be used to transfer media data.
174 When two or more links target a sink pad, only one of them can be
175 enabled at a time.</entry>
176 </row>
177 <row>
178 <entry><constant>MEDIA_LNK_FL_IMMUTABLE</constant></entry>
179 <entry>The link enabled state can't be modified at runtime. An
180 immutable link is always enabled.</entry>
181 </row>
182 </tbody>
183 </tgroup>
184 </table>
185 <para>One and only one of <constant>MEDIA_PAD_FL_SINK</constant> and
186 <constant>MEDIA_PAD_FL_SOURCE</constant> must be set for every pad.</para>
187 </refsect1>
188
189 <refsect1>
190 &return-value;
191
192 <variablelist>
193 <varlistentry>
194 <term><errorcode>EINVAL</errorcode></term>
195 <listitem>
196 <para>The &media-links-enum; <structfield>id</structfield> references
197 a non-existing entity.</para>
198 </listitem>
199 </varlistentry>
200 </variablelist>
201 </refsect1>
202</refentry>
generated by cgit v1.2.2 (git 2.25.0) at 2024-10-12 07:18:17 -0400