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

   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         </tbody>
 276       </tgroup>
 277     </table>
 278
 279     <table frame="none" pgwide="1" id="media-entity-flag">
 280       <title>Media entity flags</title>
 281       <tgroup cols="2">
 282         <colspec colname="c1"/>
 283         <colspec colname="c2"/>
 284         <tbody valign="top">
 285           <row>
 286             <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry>
 287             <entry>Default entity for its type. Used to discover the default
 288             audio, VBI and video devices, the default camera sensor, ...</entry>
 289           </row>
 290         </tbody>
 291       </tgroup>
 292     </table>
 293   </refsect1>
 294
 295   <refsect1>
 296     &return-value;
 297
 298     <variablelist>
 299       <varlistentry>
 300         <term><errorcode>EINVAL</errorcode></term>
 301         <listitem>
 302           <para>The &media-entity-desc; <structfield>id</structfield> references
 303           a non-existing entity.</para>
 304         </listitem>
 305       </varlistentry>
 306     </variablelist>
 307   </refsect1>
 308 </refentry>