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