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

Laurent Pinchart
2011-02-14T12:11:50Z

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>
> > + Arguments
> > +
> > + <variablelist>
> > + <varlistentry>
> > + <term><parameter>fd</parameter></term>
> > +
> > + File descriptor returned by
> > + <link
> > linkend='media-func-open'><function>open()</function> .
> > +
> > + </varlistentry>
> > + <varlistentry>
> > + <term><parameter>request</parameter></term>
> > +
> > + MEDIA_IOC_ENUM_LINKS
> > +
> > + </varlistentry>
> > + <varlistentry>
> > + <term><parameter>argp</parameter></term>
> > +
> > +
> > +
> > + </varlistentry>
> > + </variablelist>
> > + </refsect1>
> > +
> > + <refsect1>
> > + Description
> > +
> > + 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.
> > + 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.
> > + 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.
> > + Only forward links that originate at one of the entity's
> > source pads + are returned during the enumeration process.
> > +
> > +
> > + struct <structname>media_links_enum</structname>
> > + <tgroup cols="3">
> > + &cs-str;
> > +
> > + <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>
> > +
> > + </tgroup>
> > +
> > +
> > +
> > + struct <structname>media_pad_desc</structname>
> > + <tgroup cols="3">
> > + &cs-str;
> > +
> > + <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 for more
> > details.</entry> + </row>
> > +
> > + </tgroup>
> > +
> > +
> > +
> > + Media pad flags
> > + <tgroup cols="2">
> > + <colspec colname="c1"/>
> > + <colspec colname="c2"/>
> > +
> > + <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>
> > +
> > + </tgroup>
> > +
> > +
> > +
> > + struct <structname>media_links_enum</structname>
>
> ..the above line should perhaps be:
> > + struct <structname>media_links_desc</structname>
>
> 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