Documentation/media/uapi/mediactl/media-ioc-enum-links.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _media_ioc_enum_links:
  11
  12 **************************
  13 ioctl MEDIA_IOC_ENUM_LINKS
  14 **************************
  15
  16 Name
  17 ====
  18
  19 MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp )
  26     :name: MEDIA_IOC_ENUM_LINKS
  27
  28
  29 Arguments
  30 =========
  31
  32 ``fd``
  33     File descriptor returned by :ref:`open() <media-func-open>`.
  34
  35 ``argp``
  36     Pointer to struct :c:type:`media_links_enum`.
  37
  38
  39 Description
  40 ===========
  41
  42 To enumerate pads and/or links for a given entity, applications set the
  43 entity field of a struct :c:type:`media_links_enum`
  44 structure and initialize the struct
  45 :c:type:`media_pad_desc` and struct
  46 :c:type:`media_link_desc` structure arrays pointed by
  47 the ``pads`` and ``links`` fields. They then call the
  48 MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
  49
  50 If the ``pads`` field is not NULL, the driver fills the ``pads`` array
  51 with information about the entity's pads. The array must have enough
  52 room to store all the entity's pads. The number of pads can be retrieved
  53 with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
  54
  55 If the ``links`` field is not NULL, the driver fills the ``links`` array
  56 with information about the entity's outbound links. The array must have
  57 enough room to store all the entity's outbound links. The number of
  58 outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
  59
  60 Only forward links that originate at one of the entity's source pads are
  61 returned during the enumeration process.
  62
  63
  64 .. c:type:: media_links_enum
  65
  66 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  67
  68 .. flat-table:: struct media_links_enum
  69     :header-rows:  0
  70     :stub-columns: 0
  71     :widths:       1 1 2
  72
  73     *  -  __u32
  74        -  ``entity``
  75        -  Entity id, set by the application.
  76
  77     *  -  struct :c:type:`media_pad_desc`
  78        -  \*\ ``pads``
  79        -  Pointer to a pads array allocated by the application. Ignored if
  80           NULL.
  81
  82     *  -  struct :c:type:`media_link_desc`
  83        -  \*\ ``links``
  84        -  Pointer to a links array allocated by the application. Ignored if
  85           NULL.
  86
  87
  88 .. c:type:: media_pad_desc
  89
  90 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  91
  92 .. flat-table:: struct media_pad_desc
  93     :header-rows:  0
  94     :stub-columns: 0
  95     :widths:       1 1 2
  96
  97     *  -  __u32
  98        -  ``entity``
  99        -  ID of the entity this pad belongs to.
 100
 101     *  -  __u16
 102        -  ``index``
 103        -  Pad index, starts at 0.
 104
 105     *  -  __u32
 106        -  ``flags``
 107        -  Pad flags, see :ref:`media-pad-flag` for more details.
 108
 109     *  -  __u32
 110        -  ``reserved[2]``
 111        -  Reserved for future extensions. Drivers and applications must set
 112           the array to zero.
 113
 114
 115
 116 .. c:type:: media_link_desc
 117
 118 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 119
 120 .. flat-table:: struct media_link_desc
 121     :header-rows:  0
 122     :stub-columns: 0
 123     :widths:       1 1 2
 124
 125     *  -  struct :c:type:`media_pad_desc`
 126        -  ``source``
 127        -  Pad at the origin of this link.
 128
 129     *  -  struct :c:type:`media_pad_desc`
 130        -  ``sink``
 131        -  Pad at the target of this link.
 132
 133     *  -  __u32
 134        -  ``flags``
 135        -  Link flags, see :ref:`media-link-flag` for more details.
 136
 137     *  -  __u32
 138        -  ``reserved[4]``
 139        -  Reserved for future extensions. Drivers and applications must set
 140           the array to zero.
 141
 142
 143 Return Value
 144 ============
 145
 146 On success 0 is returned, on error -1 and the ``errno`` variable is set
 147 appropriately. The generic error codes are described at the
 148 :ref:`Generic Error Codes <gen-errors>` chapter.
 149
 150 EINVAL
 151     The struct :c:type:`media_links_enum` ``id``
 152     references a non-existing entity.