Documentation/DocBook/media/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>dev</structfield></entry>
 147             <entry></entry>
 148             <entry>Valid for (sub-)devices that create a single device node.</entry>
 149           </row>
 150           <row>
 151             <entry></entry>
 152             <entry></entry>
 153             <entry>__u32</entry>
 154             <entry><structfield>major</structfield></entry>
 155             <entry>Device node major number.</entry>
 156           </row>
 157           <row>
 158             <entry></entry>
 159             <entry></entry>
 160             <entry>__u32</entry>
 161             <entry><structfield>minor</structfield></entry>
 162             <entry>Device node minor number.</entry>
 163           </row>
 164           <row>
 165             <entry></entry>
 166             <entry>__u8</entry>
 167             <entry><structfield>raw</structfield>[184]</entry>
 168             <entry></entry>
 169             <entry></entry>
 170           </row>
 171         </tbody>
 172       </tgroup>
 173     </table>
 174
 175     <table frame="none" pgwide="1" id="media-entity-type">
 176       <title>Media entity types</title>
 177       <tgroup cols="2">
 178         <colspec colname="c1"/>
 179         <colspec colname="c2"/>
 180         <tbody valign="top">
 181           <row>
 182             <entry><constant>MEDIA_ENT_T_UNKNOWN</constant> and <constant>MEDIA_ENT_T_V4L2_SUBDEV_UNKNOWN</constant></entry>
 183             <entry>Unknown entity. That generally indicates that
 184             a driver didn't initialize properly the entity, with is a Kernel bug</entry>
 185           </row>
 186           <row>
 187             <entry><constant>MEDIA_ENT_T_V4L2_VIDEO</constant></entry>
 188             <entry>V4L video streaming input or output entity</entry>
 189           </row>
 190           <row>
 191             <entry><constant>MEDIA_ENT_T_V4L2_VBI</constant></entry>
 192             <entry>V4L VBI streaming input or output entity</entry>
 193           </row>
 194           <row>
 195             <entry><constant>MEDIA_ENT_T_V4L2_SWRADIO</constant></entry>
 196             <entry>V4L Software Digital Radio (SDR) streaming input or output entity</entry>
 197           </row>
 198           <row>
 199             <entry><constant>MEDIA_ENT_T_DVB_DEMOD</constant></entry>
 200             <entry>DVB demodulator entity</entry>
 201           </row>
 202           <row>
 203             <entry><constant>MEDIA_ENT_T_DVB_DEMUX</constant></entry>
 204             <entry>DVB demux entity. Can be implemented in hardware or in Kernelspace</entry>
 205           </row>
 206           <row>
 207             <entry><constant>MEDIA_ENT_T_DVB_TSOUT</constant></entry>
 208             <entry>DVB Transport Stream output entity</entry>
 209           </row>
 210           <row>
 211             <entry><constant>MEDIA_ENT_T_DVB_CA</constant></entry>
 212             <entry>DVB Conditional Access module (CAM) entity</entry>
 213           </row>
 214           <row>
 215             <entry><constant>MEDIA_ENT_T_DVB_DEMOD_NET_DECAP</constant></entry>
 216             <entry>DVB network ULE/MLE de-encapsulation entity. Can be implemented in hardware or in Kernelspace</entry>
 217           </row>
 218           <row>
 219             <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_SENSOR</constant></entry>
 220             <entry>Camera image sensor entity</entry>
 221           </row>
 222           <row>
 223             <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_FLASH</constant></entry>
 224             <entry>Flash controller entity</entry>
 225           </row>
 226           <row>
 227             <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_LENS</constant></entry>
 228             <entry>Lens controller entity</entry>
 229           </row>
 230           <row>
 231             <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_DECODER</constant></entry>
 232             <entry>Analog video decoder, the basic function of the video decoder
 233             is to accept analogue video from a wide variety of sources such as
 234             broadcast, DVD players, cameras and video cassette recorders, in
 235             either NTSC, PAL, SECAM or HD format, separating the stream
 236             into its component parts, luminance and chrominance, and output
 237             it in some digital video standard, with appropriate timing
 238             signals.</entry>
 239           </row>
 240           <row>
 241             <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_TUNER</constant></entry>
 242             <entry>Digital TV, analog TV, radio and/or software radio tuner</entry>
 243           </row>
 244         </tbody>
 245       </tgroup>
 246     </table>
 247
 248     <table frame="none" pgwide="1" id="media-entity-flag">
 249       <title>Media entity flags</title>
 250       <tgroup cols="2">
 251         <colspec colname="c1"/>
 252         <colspec colname="c2"/>
 253         <tbody valign="top">
 254           <row>
 255             <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry>
 256             <entry>Default entity for its type. Used to discover the default
 257             audio, VBI and video devices, the default camera sensor, ...</entry>
 258           </row>
 259         </tbody>
 260       </tgroup>
 261     </table>
 262   </refsect1>
 263
 264   <refsect1>
 265     &return-value;
 266
 267     <variablelist>
 268       <varlistentry>
 269         <term><errorcode>EINVAL</errorcode></term>
 270         <listitem>
 271           <para>The &media-entity-desc; <structfield>id</structfield> references
 272           a non-existing entity.</para>
 273         </listitem>
 274       </varlistentry>
 275     </variablelist>
 276   </refsect1>
 277 </refentry>