iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
linux/Documentation/DocBook/v4l/media-ioc-enum-entities.xml
Laurent Pinchart 1651333b09 [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>
2011-03-22 04:53:14 -03:00

309 lines
9.0 KiB
XML
Raw Blame History

<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>ALSA, VBI and video nodes that carry the same media
stream</listitem>
<listitem>lens and flash controllers associated with a sensor</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>
Reference in New Issue View Git Blame Copy Permalink