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