Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 677cb4bf authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

[media] DocBook: Document MEDIA_IOC_G_TOPOLOGY 



Add description for this new media controller ioctl.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@osg.samsung.com>
parent dc7339bf

Documentation/DocBook/media/v4l/media-controller.xml

+1 −0
Original line number Diff line number Diff line
@@ -98,6 +98,7 @@ 
  &sub-media-func-ioctl;

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

  &sub-media-ioc-device-info;

  &sub-media-ioc-g-topology;

  &sub-media-ioc-enum-entities;

  &sub-media-ioc-enum-links;

  &sub-media-ioc-setup-link;

Documentation/DocBook/media/v4l/media-ioc-g-topology.xml

0 → 100644
+391 −0
Original line number Diff line number Diff line 
<refentry id="media-g-topology">

  <refmeta>

    <refentrytitle>ioctl MEDIA_IOC_G_TOPOLOGY</refentrytitle>

    &manvol;

  </refmeta>



  <refnamediv>

    <refname>MEDIA_IOC_G_TOPOLOGY</refname>

    <refpurpose>Enumerate the graph topology and graph element 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_v2_topology *<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_G_TOPOLOGY</para>

	</listitem>

      </varlistentry>

      <varlistentry>

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

	<listitem>

	  <para></para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>



  <refsect1>

    <title>Description</title>

    <para>The typical usage of this ioctl is to call it twice.

    On the first call, the structure defined at &media-v2-topology; should

    be zeroed. At return, if no errors happen, this ioctl will return the

    <constant>topology_version</constant> and the total number of entities,

    interfaces, pads and links.</para>

    <para>Before the second call, the userspace should allocate arrays to

    store the graph elements that are desired, putting the pointers to them

    at the ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping

    the other values untouched.</para>

    <para>If the <constant>topology_version</constant> remains the same, the

    ioctl should fill the desired arrays with the media graph elements.</para>



    <table pgwide="1" frame="none" id="media-v2-topology">

      <title>struct <structname>media_v2_topology</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>__u64</entry>

	    <entry><structfield>topology_version</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Version of the media graph topology. When the graph is

		    created, this field starts with zero. Every time a graph

		    element is added or removed, this field is

		    incremented.</entry>

	  </row>

	  <row>

	    <entry>__u64</entry>

	    <entry><structfield>num_entities</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Number of entities in the graph</entry>

	  </row>

	  <row>

	    <entry>__u64</entry>

	    <entry><structfield>ptr_entities</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>A pointer to a memory area where the entities array

		   will be stored, converted to a 64-bits integer.

		   It can be zero. if zero, the ioctl won't store the

		   entities. It will just update

		   <constant>num_entities</constant></entry>

	  </row>

	  <row>

	    <entry>__u64</entry>

	    <entry><structfield>num_interfaces</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Number of interfaces in the graph</entry>

	  </row>

	  <row>

	    <entry>__u64</entry>

	    <entry><structfield>ptr_interfaces</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>A pointer to a memory area where the interfaces array

		   will be stored, converted to a 64-bits integer.

		   It can be zero. if zero, the ioctl won't store the

		   interfaces. It will just update

		   <constant>num_interfaces</constant></entry>

	  </row>

	  <row>

	    <entry>__u64</entry>

	    <entry><structfield>num_pads</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Total number of pads in the graph</entry>

	  </row>

	  <row>

	    <entry>__u64</entry>

	    <entry><structfield>ptr_pads</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>A pointer to a memory area where the pads array

		   will be stored, converted to a 64-bits integer.

		   It can be zero. if zero, the ioctl won't store the

		   pads. It will just update

		   <constant>num_pads</constant></entry>

	  </row>

	  <row>

	    <entry>__u64</entry>

	    <entry><structfield>num_links</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Total number of data and interface links in the graph</entry>

	  </row>

	  <row>

	    <entry>__u64</entry>

	    <entry><structfield>ptr_links</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>A pointer to a memory area where the links array

		   will be stored, converted to a 64-bits integer.

		   It can be zero. if zero, the ioctl won't store the

		   links. It will just update

		   <constant>num_links</constant></entry>

	  </row>

	</tbody>

      </tgroup>

    </table>



    <table pgwide="1" frame="none" id="media-v2-entity">

      <title>struct <structname>media_v2_entity</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>Unique ID for the entity.</entry>

	  </row>

	  <row>

	    <entry>char</entry>

	    <entry><structfield>name</structfield>[64]</entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Entity name as an UTF-8 NULL-terminated string.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>function</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Entity main function, see <xref linkend="media-entity-type" /> for details.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>reserved</structfield>[12]</entry>

	    <entry>Reserved for future extensions. Drivers and applications must

	    set this array to zero.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>



    <table pgwide="1" frame="none" id="media-v2-interface">

      <title>struct <structname>media_v2_interface</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>Unique ID for the interface.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>intf_type</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Interface type, see <xref linkend="media-intf-type" /> for details.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

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

	    <entry></entry>

	    <entry></entry>

	    <entry>Interface flags. Currently unused.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>reserved</structfield>[9]</entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Reserved for future extensions. Drivers and applications must

	    set this array to zero.</entry>

	  </row>

	  <row>

	    <entry>struct media_v2_intf_devnode</entry>

	    <entry><structfield>devnode</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Used only for device node interfaces. See <xref linkend="media-v2-intf-devnode" /> for details..</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>



    <table pgwide="1" frame="none" id="media-v2-intf-devnode">

      <title>struct <structname>media_v2_interface</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>major</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Device node major number.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>minor</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Device node minor number.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>



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

      <title>struct <structname>media_v2_pad</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>Unique ID for the pad.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>entity_id</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Unique ID for the entity where this pad belongs.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

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

	    <entry></entry>

	    <entry></entry>

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

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>reserved</structfield>[9]</entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Reserved for future extensions. Drivers and applications must

	    set this array to zero.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>



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

      <title>struct <structname>media_v2_pad</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>Unique ID for the pad.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>source_id</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>

	       <para>On pad to pad links: unique ID for the source pad.</para>

	       <para>On interface to entity links: unique ID for the interface.</para>

	    </entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>sink_id</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>

	       <para>On pad to pad links: unique ID for the sink pad.</para>

	       <para>On interface to entity links: unique ID for the entity.</para>

	    </entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

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

	    <entry></entry>

	    <entry></entry>

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

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>reserved</structfield>[5]</entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Reserved for future extensions. Drivers and applications must

	    set this array to zero.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>



  </refsect1>



  <refsect1>

    &return-value;



    <variablelist>

      <varlistentry>

	<term><errorcode>ENOSPC</errorcode></term>

	<listitem>

	  <para>This is returned when either one or more of the num_entities,

	  num_interfaces, num_links or num_pads are non-zero and are smaller

	  than the actual number of elements inside the graph. This may happen

	  if the <constant>topology_version</constant> changed when compared

	  to the last time this ioctl was called. Userspace should usually

	  free the area for the pointers, zero the struct elements and call

	  this ioctl again.</para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

</refentry>