Re: [alsa-devel] [PATCH v8 07/12] media: Entities, pads and links enumeration

14 Feb 2011

Hi Sylwester,
On Sunday 13 February 2011 22:59:44 Sylwester Nawrocki wrote:
...
On 2011-01-27 13:30, Laurent Pinchart wrote:
...
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@maxwell.research.nokia.com

Documentation/DocBook/media-entities.tmpl          |    8 +
 Documentation/DocBook/v4l/media-controller.xml     |    2 +
 .../DocBook/v4l/media-ioc-device-info.xml          |    3 +-
 .../DocBook/v4l/media-ioc-enum-entities.xml        |  308
 ++++++++++++++++++++ Documentation/DocBook/v4l/media-ioc-enum-links.xml
 |  202 +++++++++++++ drivers/media/media-device.c                      
 |  123 ++++++++ include/linux/media.h                              |  
 85 ++++++ include/media/media-entity.h                       |   24 +--
 8 files changed, 731 insertions(+), 24 deletions(-)
 create mode 100644 Documentation/DocBook/v4l/media-ioc-enum-entities.xml
 create mode 100644 Documentation/DocBook/v4l/media-ioc-enum-links.xml
...
...

diff --git a/Documentation/DocBook/v4l/media-ioc-enum-links.xml
b/Documentation/DocBook/v4l/media-ioc-enum-links.xml new file mode
100644
index 0000000..daf0360
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-ioc-enum-links.xml
@@ -0,0 +1,202 @@
+<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_INPUT</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_OUTPUT</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_enum</structname></title>



..the above line should perhaps be:
...

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



as "struct media_links_desc" is described above.
Thanks for catching this. I'll fix it.
...
BTW, I was wondering how one makes use of the pads associated with
a media entity of type other than MEDIA_ENT_T_V4L2_SUBDEV*,
e.g. V4L2 device - MEDIA_ENT_T_DEVNODE_V4L.
I guess new standard ioctls should be added for per pads operations
at V4L2 device, similarly is it is done with v4l2-subdevs.
Is this right?
I don't think we need now ioctls there. As DEVNODE_V4L entities are just an 
interface between the driver and userspace, applications should use V4L2 
ioctls on the video device node.
For non-V4L entities other ioctls will obviously be needed, but they will be 
defined by other subsystems such as ALSA (provided the entities have a device 
node).
-- 
Regards,

Laurent Pinchart

    

Laurent Pinchart

tags (0)

participants (1)