0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: MC
0003
0004 .. _media_ioc_enum_links:
0005
0006 **************************
0007 ioctl MEDIA_IOC_ENUM_LINKS
0008 **************************
0009
0010 Name
0011 ====
0012
0013 MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: MEDIA_IOC_ENUM_LINKS
0019
0020 ``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`media_links_enum`.
0030
0031 Description
0032 ===========
0033
0034 To enumerate pads and/or links for a given entity, applications set the
0035 entity field of a struct :c:type:`media_links_enum`
0036 structure and initialize the struct
0037 :c:type:`media_pad_desc` and struct
0038 :c:type:`media_link_desc` structure arrays pointed by
0039 the ``pads`` and ``links`` fields. They then call the
0040 MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
0041
0042 If the ``pads`` field is not NULL, the driver fills the ``pads`` array
0043 with information about the entity's pads. The array must have enough
0044 room to store all the entity's pads. The number of pads can be retrieved
0045 with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
0046
0047 If the ``links`` field is not NULL, the driver fills the ``links`` array
0048 with information about the entity's outbound links. The array must have
0049 enough room to store all the entity's outbound links. The number of
0050 outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
0051
0052 Only forward links that originate at one of the entity's source pads are
0053 returned during the enumeration process.
0054
0055 .. c:type:: media_links_enum
0056
0057 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0058
0059 .. flat-table:: struct media_links_enum
0060 :header-rows: 0
0061 :stub-columns: 0
0062 :widths: 1 1 2
0063
0064 * - __u32
0065 - ``entity``
0066 - Entity id, set by the application.
0067
0068 * - struct :c:type:`media_pad_desc`
0069 - \*\ ``pads``
0070 - Pointer to a pads array allocated by the application. Ignored if
0071 NULL.
0072
0073 * - struct :c:type:`media_link_desc`
0074 - \*\ ``links``
0075 - Pointer to a links array allocated by the application. Ignored if
0076 NULL.
0077
0078 * - __u32
0079 - ``reserved[4]``
0080 - Reserved for future extensions. Drivers and applications must set
0081 the array to zero.
0082
0083 .. c:type:: media_pad_desc
0084
0085 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0086
0087 .. flat-table:: struct media_pad_desc
0088 :header-rows: 0
0089 :stub-columns: 0
0090 :widths: 1 1 2
0091
0092 * - __u32
0093 - ``entity``
0094 - ID of the entity this pad belongs to.
0095
0096 * - __u16
0097 - ``index``
0098 - Pad index, starts at 0.
0099
0100 * - __u32
0101 - ``flags``
0102 - Pad flags, see :ref:`media-pad-flag` for more details.
0103
0104 * - __u32
0105 - ``reserved[2]``
0106 - Reserved for future extensions. Drivers and applications must set
0107 the array to zero.
0108
0109
0110 .. c:type:: media_link_desc
0111
0112 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0113
0114 .. flat-table:: struct media_link_desc
0115 :header-rows: 0
0116 :stub-columns: 0
0117 :widths: 1 1 2
0118
0119 * - struct :c:type:`media_pad_desc`
0120 - ``source``
0121 - Pad at the origin of this link.
0122
0123 * - struct :c:type:`media_pad_desc`
0124 - ``sink``
0125 - Pad at the target of this link.
0126
0127 * - __u32
0128 - ``flags``
0129 - Link flags, see :ref:`media-link-flag` for more details.
0130
0131 * - __u32
0132 - ``reserved[2]``
0133 - Reserved for future extensions. Drivers and applications must set
0134 the array to zero.
0135
0136 Return Value
0137 ============
0138
0139 On success 0 is returned, on error -1 and the ``errno`` variable is set
0140 appropriately. The generic error codes are described at the
0141 :ref:`Generic Error Codes <gen-errors>` chapter.
0142
0143 EINVAL
0144 The struct :c:type:`media_links_enum` ``id``
0145 references a non-existing entity.
