1<refentry id="media-ioc-enum-entities"> 2 <refmeta> 3 <refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle> 4 &manvol; 5 </refmeta> 6 7 <refnamediv> 8 <refname>MEDIA_IOC_ENUM_ENTITIES</refname> 9 <refpurpose>Enumerate entities and their properties</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_entity_desc *<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_ENTITIES</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 <para>To query the attributes of an entity, applications set the id field 52 of a &media-entity-desc; structure and call the MEDIA_IOC_ENUM_ENTITIES 53 ioctl with a pointer to this structure. The driver fills the rest of the 54 structure or returns an &EINVAL; when the id is invalid.</para> 55 <para>Entities can be enumerated by or'ing the id with the 56 <constant>MEDIA_ENT_ID_FLAG_NEXT</constant> flag. The driver will return 57 information about the entity with the smallest id strictly larger than the 58 requested one ('next entity'), or the &EINVAL; if there is none.</para> 59 <para>Entity IDs can be non-contiguous. Applications must 60 <emphasis>not</emphasis> try to enumerate entities by calling 61 MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para> 62 <para>Two or more entities that share a common non-zero 63 <structfield>group_id</structfield> value are considered as logically 64 grouped. Groups are used to report 65 <itemizedlist> 66 <listitem><para>ALSA, VBI and video nodes that carry the same media 67 stream</para></listitem> 68 <listitem><para>lens and flash controllers associated with a sensor</para></listitem> 69 </itemizedlist> 70 </para> 71 72 <table pgwide="1" frame="none" id="media-entity-desc"> 73 <title>struct <structname>media_entity_desc</structname></title> 74 <tgroup cols="5"> 75 <colspec colname="c1" /> 76 <colspec colname="c2" /> 77 <colspec colname="c3" /> 78 <colspec colname="c4" /> 79 <colspec colname="c5" /> 80 <tbody valign="top"> 81 <row> 82 <entry>__u32</entry> 83 <entry><structfield>id</structfield></entry> 84 <entry></entry> 85 <entry></entry> 86 <entry>Entity id, set by the application. When the id is or'ed with 87 <constant>MEDIA_ENT_ID_FLAG_NEXT</constant>, the driver clears the 88 flag and returns the first entity with a larger id.</entry> 89 </row> 90 <row> 91 <entry>char</entry> 92 <entry><structfield>name</structfield>[32]</entry> 93 <entry></entry> 94 <entry></entry> 95 <entry>Entity name as an UTF-8 NULL-terminated string.</entry> 96 </row> 97 <row> 98 <entry>__u32</entry> 99 <entry><structfield>type</structfield></entry> 100 <entry></entry> 101 <entry></entry> 102 <entry>Entity type, see <xref linkend="media-entity-type" /> for details.</entry> 103 </row> 104 <row> 105 <entry>__u32</entry> 106 <entry><structfield>revision</structfield></entry> 107 <entry></entry> 108 <entry></entry> 109 <entry>Entity revision in a driver/hardware specific format.</entry> 110 </row> 111 <row> 112 <entry>__u32</entry> 113 <entry><structfield>flags</structfield></entry> 114 <entry></entry> 115 <entry></entry> 116 <entry>Entity flags, see <xref linkend="media-entity-flag" /> for details.</entry> 117 </row> 118 <row> 119 <entry>__u32</entry> 120 <entry><structfield>group_id</structfield></entry> 121 <entry></entry> 122 <entry></entry> 123 <entry>Entity group ID</entry> 124 </row> 125 <row> 126 <entry>__u16</entry> 127 <entry><structfield>pads</structfield></entry> 128 <entry></entry> 129 <entry></entry> 130 <entry>Number of pads</entry> 131 </row> 132 <row> 133 <entry>__u16</entry> 134 <entry><structfield>links</structfield></entry> 135 <entry></entry> 136 <entry></entry> 137 <entry>Total number of outbound links. Inbound links are not counted 138 in this field.</entry> 139 </row> 140 <row> 141 <entry>union</entry> 142 </row> 143 <row> 144 <entry></entry> 145 <entry>struct</entry> 146 <entry><structfield>v4l</structfield></entry> 147 <entry></entry> 148 <entry>Valid for V4L sub-devices and nodes only.</entry> 149 </row> 150 <row> 151 <entry></entry> 152 <entry></entry> 153 <entry>__u32</entry> 154 <entry><structfield>major</structfield></entry> 155 <entry>V4L device node major number. For V4L sub-devices with no 156 device node, set by the driver to 0.</entry> 157 </row> 158 <row> 159 <entry></entry> 160 <entry></entry> 161 <entry>__u32</entry> 162 <entry><structfield>minor</structfield></entry> 163 <entry>V4L device node minor number. For V4L sub-devices with no 164 device node, set by the driver to 0.</entry> 165 </row> 166 <row> 167 <entry></entry> 168 <entry>struct</entry> 169 <entry><structfield>fb</structfield></entry> 170 <entry></entry> 171 <entry>Valid for frame buffer nodes only.</entry> 172 </row> 173 <row> 174 <entry></entry> 175 <entry></entry> 176 <entry>__u32</entry> 177 <entry><structfield>major</structfield></entry> 178 <entry>Frame buffer device node major number.</entry> 179 </row> 180 <row> 181 <entry></entry> 182 <entry></entry> 183 <entry>__u32</entry> 184 <entry><structfield>minor</structfield></entry> 185 <entry>Frame buffer device node minor number.</entry> 186 </row> 187 <row> 188 <entry></entry> 189 <entry>struct</entry> 190 <entry><structfield>alsa</structfield></entry> 191 <entry></entry> 192 <entry>Valid for ALSA devices only.</entry> 193 </row> 194 <row> 195 <entry></entry> 196 <entry></entry> 197 <entry>__u32</entry> 198 <entry><structfield>card</structfield></entry> 199 <entry>ALSA card number</entry> 200 </row> 201 <row> 202 <entry></entry> 203 <entry></entry> 204 <entry>__u32</entry> 205 <entry><structfield>device</structfield></entry> 206 <entry>ALSA device number</entry> 207 </row> 208 <row> 209 <entry></entry> 210 <entry></entry> 211 <entry>__u32</entry> 212 <entry><structfield>subdevice</structfield></entry> 213 <entry>ALSA sub-device number</entry> 214 </row> 215 <row> 216 <entry></entry> 217 <entry>int</entry> 218 <entry><structfield>dvb</structfield></entry> 219 <entry></entry> 220 <entry>DVB card number</entry> 221 </row> 222 <row> 223 <entry></entry> 224 <entry>__u8</entry> 225 <entry><structfield>raw</structfield>[180]</entry> 226 <entry></entry> 227 <entry></entry> 228 </row> 229 </tbody> 230 </tgroup> 231 </table> 232 233 <table frame="none" pgwide="1" id="media-entity-type"> 234 <title>Media entity types</title> 235 <tgroup cols="2"> 236 <colspec colname="c1"/> 237 <colspec colname="c2"/> 238 <tbody valign="top"> 239 <row> 240 <entry><constant>MEDIA_ENT_T_DEVNODE</constant></entry> 241 <entry>Unknown device node</entry> 242 </row> 243 <row> 244 <entry><constant>MEDIA_ENT_T_DEVNODE_V4L</constant></entry> 245 <entry>V4L video, radio or vbi device node</entry> 246 </row> 247 <row> 248 <entry><constant>MEDIA_ENT_T_DEVNODE_FB</constant></entry> 249 <entry>Frame buffer device node</entry> 250 </row> 251 <row> 252 <entry><constant>MEDIA_ENT_T_DEVNODE_ALSA</constant></entry> 253 <entry>ALSA card</entry> 254 </row> 255 <row> 256 <entry><constant>MEDIA_ENT_T_DEVNODE_DVB</constant></entry> 257 <entry>DVB card</entry> 258 </row> 259 <row> 260 <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV</constant></entry> 261 <entry>Unknown V4L sub-device</entry> 262 </row> 263 <row> 264 <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_SENSOR</constant></entry> 265 <entry>Video sensor</entry> 266 </row> 267 <row> 268 <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_FLASH</constant></entry> 269 <entry>Flash controller</entry> 270 </row> 271 <row> 272 <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_LENS</constant></entry> 273 <entry>Lens controller</entry> 274 </row> 275 <row> 276 <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_DECODER</constant></entry> 277 <entry>Video decoder, the basic function of the video decoder is to 278 accept analogue video from a wide variety of sources such as 279 broadcast, DVD players, cameras and video cassette recorders, in 280 either NTSC, PAL or HD format and still occasionally SECAM, separate 281 it into its component parts, luminance and chrominance, and output 282 it in some digital video standard, with appropriate embedded timing 283 signals.</entry> 284 </row> 285 </tbody> 286 </tgroup> 287 </table> 288 289 <table frame="none" pgwide="1" id="media-entity-flag"> 290 <title>Media entity flags</title> 291 <tgroup cols="2"> 292 <colspec colname="c1"/> 293 <colspec colname="c2"/> 294 <tbody valign="top"> 295 <row> 296 <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry> 297 <entry>Default entity for its type. Used to discover the default 298 audio, VBI and video devices, the default camera sensor, ...</entry> 299 </row> 300 </tbody> 301 </tgroup> 302 </table> 303 </refsect1> 304 305 <refsect1> 306 &return-value; 307 308 <variablelist> 309 <varlistentry> 310 <term><errorcode>EINVAL</errorcode></term> 311 <listitem> 312 <para>The &media-entity-desc; <structfield>id</structfield> references 313 a non-existing entity.</para> 314 </listitem> 315 </varlistentry> 316 </variablelist> 317 </refsect1> 318</refentry> 319