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

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _media_ioc_enum_links:
   4
   5 **************************
   6 ioctl MEDIA_IOC_ENUM_LINKS
   7 **************************
   8
   9 Name
  10 ====
  11
  12 MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct media_links_enum *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <media-func-open>`.
  26
  27 ``request``
  28     MEDIA_IOC_ENUM_LINKS
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 To enumerate pads and/or links for a given entity, applications set the
  37 entity field of a struct :ref:`media_links_enum <media-links-enum>`
  38 structure and initialize the struct
  39 :ref:`media_pad_desc <media-pad-desc>` and struct
  40 :ref:`media_link_desc <media-link-desc>` structure arrays pointed by
  41 the ``pads`` and ``links`` fields. They then call the
  42 MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
  43
  44 If the ``pads`` field is not NULL, the driver fills the ``pads`` array
  45 with information about the entity's pads. The array must have enough
  46 room to store all the entity's pads. The number of pads can be retrieved
  47 with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
  48
  49 If the ``links`` field is not NULL, the driver fills the ``links`` array
  50 with information about the entity's outbound links. The array must have
  51 enough room to store all the entity's outbound links. The number of
  52 outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
  53
  54 Only forward links that originate at one of the entity's source pads are
  55 returned during the enumeration process.
  56
  57
  58 .. _media-links-enum:
  59
  60 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  61
  62 .. flat-table:: struct media_links_enum
  63     :header-rows:  0
  64     :stub-columns: 0
  65     :widths:       1 1 2
  66
  67
  68     -  .. row 1
  69
  70        -  __u32
  71
  72        -  ``entity``
  73
  74        -  Entity id, set by the application.
  75
  76     -  .. row 2
  77
  78        -  struct :ref:`media_pad_desc <media-pad-desc>`
  79
  80        -  \*\ ``pads``
  81
  82        -  Pointer to a pads array allocated by the application. Ignored if
  83           NULL.
  84
  85     -  .. row 3
  86
  87        -  struct :ref:`media_link_desc <media-link-desc>`
  88
  89        -  \*\ ``links``
  90
  91        -  Pointer to a links array allocated by the application. Ignored if
  92           NULL.
  93
  94
  95
  96 .. _media-pad-desc:
  97
  98 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  99
 100 .. flat-table:: struct media_pad_desc
 101     :header-rows:  0
 102     :stub-columns: 0
 103     :widths:       1 1 2
 104
 105
 106     -  .. row 1
 107
 108        -  __u32
 109
 110        -  ``entity``
 111
 112        -  ID of the entity this pad belongs to.
 113
 114     -  .. row 2
 115
 116        -  __u16
 117
 118        -  ``index``
 119
 120        -  0-based pad index.
 121
 122     -  .. row 3
 123
 124        -  __u32
 125
 126        -  ``flags``
 127
 128        -  Pad flags, see :ref:`media-pad-flag` for more details.
 129
 130
 131
 132 .. _media-link-desc:
 133
 134 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 135
 136 .. flat-table:: struct media_link_desc
 137     :header-rows:  0
 138     :stub-columns: 0
 139     :widths:       1 1 2
 140
 141
 142     -  .. row 1
 143
 144        -  struct :ref:`media_pad_desc <media-pad-desc>`
 145
 146        -  ``source``
 147
 148        -  Pad at the origin of this link.
 149
 150     -  .. row 2
 151
 152        -  struct :ref:`media_pad_desc <media-pad-desc>`
 153
 154        -  ``sink``
 155
 156        -  Pad at the target of this link.
 157
 158     -  .. row 3
 159
 160        -  __u32
 161
 162        -  ``flags``
 163
 164        -  Link flags, see :ref:`media-link-flag` for more details.
 165
 166
 167 Return Value
 168 ============
 169
 170 On success 0 is returned, on error -1 and the ``errno`` variable is set
 171 appropriately. The generic error codes are described at the
 172 :ref:`Generic Error Codes <gen-errors>` chapter.
 173
 174 EINVAL
 175     The struct :ref:`media_links_enum <media-links-enum>` ``id``
 176     references a non-existing entity.