Documentation/userspace-api/media/mediactl/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 **************************
   7 ioctl MEDIA_IOC_ENUM_LINKS
   8 **************************
   9
  10 Name
  11 ====
  12
  13 MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
  14
  15 Synopsis
  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
  22 Arguments
  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
  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 .. 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
 136 Return Value
 137 ============
 138
 139 On success 0 is returned, on error -1 and the ``errno`` variable is set
 140 appropriately. The generic error codes are described at the
 141 :ref:`Generic Error Codes <gen-errors>` chapter.
 142
 143 EINVAL
 144     The struct :c:type:`media_links_enum` ``id``
 145     references a non-existing entity.