Commit 1651333b authored by Laurent Pinchart's avatar Laurent Pinchart Committed by Mauro Carvalho Chehab
Browse files

[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: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: default avatarSakari Ailus <sakari.ailus@iki.fi>
Acked-by: default avatarHans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 140d8816

Documentation/DocBook/media-entities.tmpl

+8 −0
Original line number Diff line number Diff line
@@ -92,6 +92,8 @@ 
<!ENTITY VIDIOC-UNSUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_UNSUBSCRIBE_EVENT</constant></link>">



<!ENTITY MEDIA-IOC-DEVICE-INFO "<link linkend='media-ioc-device-info'><constant>MEDIA_IOC_DEVICE_INFO</constant></link>">

<!ENTITY MEDIA-IOC-ENUM-ENTITIES "<link linkend='media-ioc-enum-entities'><constant>MEDIA_IOC_ENUM_ENTITIES</constant></link>">

<!ENTITY MEDIA-IOC-ENUM-LINKS "<link linkend='media-ioc-enum-links'><constant>MEDIA_IOC_ENUM_LINKS</constant></link>">



<!-- Types -->

<!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>">
@@ -191,6 +193,10 @@ 
<!ENTITY v4l2-window "struct&nbsp;<link linkend='v4l2-window'>v4l2_window</link>">



<!ENTITY media-device-info "struct&nbsp;<link linkend='media-device-info'>media_device_info</link>">

<!ENTITY media-entity-desc "struct&nbsp;<link linkend='media-entity-desc'>media_entity_desc</link>">

<!ENTITY media-links-enum "struct&nbsp;<link linkend='media-links-enum'>media_links_enum</link>">

<!ENTITY media-pad-desc "struct&nbsp;<link linkend='media-pad-desc'>media_pad_desc</link>">

<!ENTITY media-link-desc "struct&nbsp;<link linkend='media-link-desc'>media_link_desc</link>">



<!-- Error Codes -->

<!ENTITY EACCES "<errorcode>EACCES</errorcode> error code">
@@ -340,6 +346,8 @@ 
<!ENTITY sub-media-close SYSTEM "v4l/media-func-close.xml">

<!ENTITY sub-media-ioctl SYSTEM "v4l/media-func-ioctl.xml">

<!ENTITY sub-media-ioc-device-info SYSTEM "v4l/media-ioc-device-info.xml">

<!ENTITY sub-media-ioc-enum-entities SYSTEM "v4l/media-ioc-enum-entities.xml">

<!ENTITY sub-media-ioc-enum-links SYSTEM "v4l/media-ioc-enum-links.xml">



<!-- Function Reference -->

<!ENTITY close SYSTEM "v4l/func-close.xml">

Documentation/DocBook/v4l/media-controller.xml

+2 −0
Original line number Diff line number Diff line
@@ -83,4 +83,6 @@ 
  &sub-media-ioctl;

  <!-- All ioctls go here. -->

  &sub-media-ioc-device-info;

  &sub-media-ioc-enum-entities;

  &sub-media-ioc-enum-links;

</appendix>

Documentation/DocBook/v4l/media-ioc-device-info.xml

+2 −1
Original line number Diff line number Diff line
@@ -27,7 +27,8 @@ 
      <varlistentry>

	<term><parameter>fd</parameter></term>

	<listitem>

	  <para>&fd;</para>

	  <para>File descriptor returned by

	  <link linkend='media-func-open'><function>open()</function></link>.</para>

	</listitem>

      </varlistentry>

      <varlistentry>

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

0 → 100644
+308 −0
Original line number Diff line number Diff line 
<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>

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

0 → 100644
+202 −0
Original line number Diff line number Diff line 
<refentry id="media-ioc-enum-links">

  <refmeta>

    <refentrytitle>ioctl MEDIA_IOC_ENUM_LINKS</refentrytitle>

    &manvol;

  </refmeta>



  <refnamediv>

    <refname>MEDIA_IOC_ENUM_LINKS</refname>

    <refpurpose>Enumerate all pads and links for a given entity</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_links_enum *<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_LINKS</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><parameter>argp</parameter></term>

	<listitem>

	  <para></para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>



  <refsect1>

    <title>Description</title>



    <para>To enumerate pads and/or links for a given entity, applications set

    the entity field of a &media-links-enum; structure and initialize the

    &media-pad-desc; and &media-link-desc; structure arrays pointed by the

    <structfield>pads</structfield> and <structfield>links</structfield> fields.

    They then call the MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this

    structure.</para>

    <para>If the <structfield>pads</structfield> field is not NULL, the driver

    fills the <structfield>pads</structfield> array with information about the

    entity's pads. The array must have enough room to store all the entity's

    pads. The number of pads can be retrieved with the &MEDIA-IOC-ENUM-ENTITIES;

    ioctl.</para>

    <para>If the <structfield>links</structfield> field is not NULL, the driver

    fills the <structfield>links</structfield> array with information about the

    entity's outbound links. The array must have enough room to store all the

    entity's outbound links. The number of outbound links can be retrieved with

    the &MEDIA-IOC-ENUM-ENTITIES; ioctl.</para>

    <para>Only forward links that originate at one of the entity's source pads

    are returned during the enumeration process.</para>



    <table pgwide="1" frame="none" id="media-links-enum">

      <title>struct <structname>media_links_enum</structname></title>

      <tgroup cols="3">

        &cs-str;

	<tbody valign="top">

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>entity</structfield></entry>

	    <entry>Entity id, set by the application.</entry>

	  </row>

	  <row>

	    <entry>struct &media-pad-desc;</entry>

	    <entry>*<structfield>pads</structfield></entry>

	    <entry>Pointer to a pads array allocated by the application. Ignored

	    if NULL.</entry>

	  </row>

	  <row>

	    <entry>struct &media-link-desc;</entry>

	    <entry>*<structfield>links</structfield></entry>

	    <entry>Pointer to a links array allocated by the application. Ignored

	    if NULL.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>



    <table pgwide="1" frame="none" id="media-pad-desc">

      <title>struct <structname>media_pad_desc</structname></title>

      <tgroup cols="3">

        &cs-str;

	<tbody valign="top">

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>entity</structfield></entry>

	    <entry>ID of the entity this pad belongs to.</entry>

	  </row>

	  <row>

	    <entry>__u16</entry>

	    <entry><structfield>index</structfield></entry>

	    <entry>0-based pad index.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>flags</structfield></entry>

	    <entry>Pad flags, see <xref linkend="media-pad-flag" /> for more details.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>



    <table frame="none" pgwide="1" id="media-pad-flag">

      <title>Media pad flags</title>

      <tgroup cols="2">

        <colspec colname="c1"/>

        <colspec colname="c2"/>

	<tbody valign="top">

	  <row>

	    <entry><constant>MEDIA_PAD_FL_SINK</constant></entry>

	    <entry>Input pad, relative to the entity. Input pads sink data and

	    are targets of links.</entry>

	  </row>

	  <row>

	    <entry><constant>MEDIA_PAD_FL_SOURCE</constant></entry>

	    <entry>Output pad, relative to the entity. Output pads source data

	    and are origins of links.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>



    <table pgwide="1" frame="none" id="media-link-desc">

      <title>struct <structname>media_links_desc</structname></title>

      <tgroup cols="3">

        &cs-str;

	<tbody valign="top">

	  <row>

	    <entry>struct &media-pad-desc;</entry>

	    <entry><structfield>source</structfield></entry>

	    <entry>Pad at the origin of this link.</entry>

	  </row>

	  <row>

	    <entry>struct &media-pad-desc;</entry>

	    <entry><structfield>sink</structfield></entry>

	    <entry>Pad at the target of this link.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>flags</structfield></entry>

	    <entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>



    <table frame="none" pgwide="1" id="media-link-flag">

      <title>Media link flags</title>

      <tgroup cols="2">

        <colspec colname="c1"/>

        <colspec colname="c2"/>

	<tbody valign="top">

	  <row>

	    <entry><constant>MEDIA_LNK_FL_ENABLED</constant></entry>

	    <entry>The link is enabled and can be used to transfer media data.

	    When two or more links target a sink pad, only one of them can be

	    enabled at a time.</entry>

	  </row>

	  <row>

	    <entry><constant>MEDIA_LNK_FL_IMMUTABLE</constant></entry>

	    <entry>The link enabled state can't be modified at runtime. An

	    immutable link is always enabled.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>

    <para>One and only one of <constant>MEDIA_PAD_FL_SINK</constant> and

    <constant>MEDIA_PAD_FL_SOURCE</constant> must be set for every pad.</para>

  </refsect1>



  <refsect1>

    &return-value;



    <variablelist>

      <varlistentry>

	<term><errorcode>EINVAL</errorcode></term>

	<listitem>

	  <para>The &media-links-enum; <structfield>id</structfield> references

	  a non-existing entity.</para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

</refentry>

CRA Git | Maintained and supported by SUSTech CRA and CCSE