Documentation/media/uapi/mediactl/media-ioc-enum-links.rst

   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/media/uapi/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 **************************
  13 ioctl MEDIA_IOC_ENUM_LINKS
  14 **************************
  15
  16 Name
  17 ====
  18
  19 MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
  20
  21
  22 Synopsis
  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
  29 Arguments
  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
  39 Description
  40 ===========
  41
  42 To enumerate pads and/or links for a given entity, applications set the
  43 entity field of a struct :c:type:`media_links_enum`
  44 structure and initialize the struct
  45 :c:type:`media_pad_desc` and struct
  46 :c:type:`media_link_desc` structure arrays pointed by
  47 the ``pads`` and ``links`` fields. They then call the
  48 MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
  49
  50 If the ``pads`` field is not NULL, the driver fills the ``pads`` array
  51 with information about the entity's pads. The array must have enough
  52 room to store all the entity's pads. The number of pads can be retrieved
  53 with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
  54
  55 If the ``links`` field is not NULL, the driver fills the ``links`` array
  56 with information about the entity's outbound links. The array must have
  57 enough room to store all the entity's outbound links. The number of
  58 outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
  59
  60 Only forward links that originate at one of the entity's source pads are
  61 returned 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
 148 Return Value
 149 ============
 150
 151 On success 0 is returned, on error -1 and the ``errno`` variable is set
 152 appropriately. The generic error codes are described at the
 153 :ref:`Generic Error Codes <gen-errors>` chapter.
 154
 155 EINVAL
 156     The struct :c:type:`media_links_enum` ``id``
 157     references a non-existing entity.