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. 146