media-ioc-enum-links.rst

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