diff options
Diffstat (limited to 'Documentation/DocBook/v4l/media-ioc-enum-entities.xml')
| -rw-r--r-- | Documentation/DocBook/v4l/media-ioc-enum-entities.xml | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/media-ioc-enum-entities.xml b/Documentation/DocBook/v4l/media-ioc-enum-entities.xml new file mode 100644 index 00000000000..576b68b33f2 --- /dev/null +++ b/Documentation/DocBook/v4l/media-ioc-enum-entities.xml @@ -0,0 +1,308 @@ +<refentry id="media-ioc-enum-entities"> + <refmeta> + <refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>MEDIA_IOC_ENUM_ENTITIES</refname> + <refpurpose>Enumerate entities and their properties</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_entity_desc *<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_ENTITIES</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + <para>To query the attributes of an entity, applications set the id field + of a &media-entity-desc; structure and call the MEDIA_IOC_ENUM_ENTITIES + ioctl with a pointer to this structure. The driver fills the rest of the + structure or returns an &EINVAL; when the id is invalid.</para> + <para>Entities can be enumerated by or'ing the id with the + <constant>MEDIA_ENT_ID_FLAG_NEXT</constant> flag. The driver will return + information about the entity with the smallest id strictly larger than the + requested one ('next entity'), or the &EINVAL; if there is none.</para> + <para>Entity IDs can be non-contiguous. Applications must + <emphasis>not</emphasis> try to enumerate entities by calling + MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para> + <para>Two or more entities that share a common non-zero + <structfield>group_id</structfield> value are considered as logically + grouped. Groups are used to report + <itemizedlist> + <listitem><para>ALSA, VBI and video nodes that carry the same media + stream</para></listitem> + <listitem><para>lens and flash controllers associated with a sensor</para></listitem> + </itemizedlist> + </para> + + <table pgwide="1" frame="none" id="media-entity-desc"> + <title>struct <structname>media_entity_desc</structname></title> + <tgroup cols="5"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>id</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Entity id, set by the application. When the id is or'ed with + <constant>MEDIA_ENT_ID_FLAG_NEXT</constant>, the driver clears the + flag and returns the first entity with a larger id.</entry> + </row> + <row> + <entry>char</entry> + <entry><structfield>name</structfield>[32]</entry> + <entry></entry> + <entry></entry> + <entry>Entity name as an UTF-8 NULL-terminated string.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>type</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Entity type, see <xref linkend="media-entity-type" /> for details.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>revision</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Entity revision in a driver/hardware specific format.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Entity flags, see <xref linkend="media-entity-flag" /> for details.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>group_id</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Entity group ID</entry> + </row> + <row> + <entry>__u16</entry> + <entry><structfield>pads</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Number of pads</entry> + </row> + <row> + <entry>__u16</entry> + <entry><structfield>links</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Total number of outbound links. Inbound links are not counted + in this field.</entry> + </row> + <row> + <entry>union</entry> + </row> + <row> + <entry></entry> + <entry>struct</entry> + <entry><structfield>v4l</structfield></entry> + <entry></entry> + <entry>Valid for V4L sub-devices and nodes only.</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>major</structfield></entry> + <entry>V4L device node major number. For V4L sub-devices with no + device node, set by the driver to 0.</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>minor</structfield></entry> + <entry>V4L device node minor number. For V4L sub-devices with no + device node, set by the driver to 0.</entry> + </row> + <row> + <entry></entry> + <entry>struct</entry> + <entry><structfield>fb</structfield></entry> + <entry></entry> + <entry>Valid for frame buffer nodes only.</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>major</structfield></entry> + <entry>Frame buffer device node major number.</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>minor</structfield></entry> + <entry>Frame buffer device node minor number.</entry> + </row> + <row> + <entry></entry> + <entry>struct</entry> + <entry><structfield>alsa</structfield></entry> + <entry></entry> + <entry>Valid for ALSA devices only.</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>card</structfield></entry> + <entry>ALSA card number</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>device</structfield></entry> + <entry>ALSA device number</entry> + </row> + <row> + <entry></entry> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>subdevice</structfield></entry> + <entry>ALSA sub-device number</entry> + </row> + <row> + <entry></entry> + <entry>int</entry> + <entry><structfield>dvb</structfield></entry> + <entry></entry> + <entry>DVB card number</entry> + </row> + <row> + <entry></entry> + <entry>__u8</entry> + <entry><structfield>raw</structfield>[180]</entry> + <entry></entry> + <entry></entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="media-entity-type"> + <title>Media entity types</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_ENT_T_DEVNODE</constant></entry> + <entry>Unknown device node</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_DEVNODE_V4L</constant></entry> + <entry>V4L video, radio or vbi device node</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_DEVNODE_FB</constant></entry> + <entry>Frame buffer device node</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_DEVNODE_ALSA</constant></entry> + <entry>ALSA card</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_DEVNODE_DVB</constant></entry> + <entry>DVB card</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV</constant></entry> + <entry>Unknown V4L sub-device</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_SENSOR</constant></entry> + <entry>Video sensor</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_FLASH</constant></entry> + <entry>Flash controller</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_LENS</constant></entry> + <entry>Lens controller</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="media-entity-flag"> + <title>Media entity flags</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry> + <entry>Default entity for its type. Used to discover the default + audio, VBI and video devices, the default camera sensor, ...</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The &media-entity-desc; <structfield>id</structfield> references + a non-existing entity.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> |