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

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _media_ioc_enum_links:
   4
   5 **************************
   6 ioctl MEDIA_IOC_ENUM_LINKS
   7 **************************
   8
   9 Name
  10 ====
  11
  12 MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp )
  19     :name: MEDIA_IOC_ENUM_LINKS
  20
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :ref:`open() <media-func-open>`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`media_links_enum`.
  30
  31
  32 Description
  33 ===========
  34
  35 To enumerate pads and/or links for a given entity, applications set the
  36 entity field of a struct :c:type:`media_links_enum`
  37 structure and initialize the struct
  38 :c:type:`media_pad_desc` and struct
  39 :c:type:`media_link_desc` structure arrays pointed by
  40 the ``pads`` and ``links`` fields. They then call the
  41 MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
  42
  43 If the ``pads`` field is not NULL, the driver fills the ``pads`` array
  44 with information about the entity's pads. The array must have enough
  45 room to store all the entity's pads. The number of pads can be retrieved
  46 with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
  47
  48 If the ``links`` field is not NULL, the driver fills the ``links`` array
  49 with information about the entity's outbound links. The array must have
  50 enough room to store all the entity's outbound links. The number of
  51 outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
  52
  53 Only forward links that originate at one of the entity's source pads are
  54 returned during the enumeration process.
  55
  56
  57 .. c:type:: media_links_enum
  58
  59 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  60
  61 .. flat-table:: struct media_links_enum
  62     :header-rows:  0
  63     :stub-columns: 0
  64     :widths:       1 1 2
  65
  66     *  -  __u32
  67        -  ``entity``
  68        -  Entity id, set by the application.
  69
  70     *  -  struct :c:type:`media_pad_desc`
  71        -  \*\ ``pads``
  72        -  Pointer to a pads array allocated by the application. Ignored if
  73           NULL.
  74
  75     *  -  struct :c:type:`media_link_desc`
  76        -  \*\ ``links``
  77        -  Pointer to a links array allocated by the application. Ignored if
  78           NULL.
  79
  80
  81 .. c:type:: media_pad_desc
  82
  83 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  84
  85 .. flat-table:: struct media_pad_desc
  86     :header-rows:  0
  87     :stub-columns: 0
  88     :widths:       1 1 2
  89
  90     *  -  __u32
  91        -  ``entity``
  92        -  ID of the entity this pad belongs to.
  93
  94     *  -  __u16
  95        -  ``index``
  96        -  Pad index, starts at 0.
  97
  98     *  -  __u32
  99        -  ``flags``
 100        -  Pad flags, see :ref:`media-pad-flag` for more details.
 101
 102     *  -  __u32
 103        -  ``reserved[2]``
 104        -  Reserved for future extensions. Drivers and applications must set
 105           the array to zero.
 106
 107
 108
 109 .. c:type:: media_link_desc
 110
 111 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 112
 113 .. flat-table:: struct media_link_desc
 114     :header-rows:  0
 115     :stub-columns: 0
 116     :widths:       1 1 2
 117
 118     *  -  struct :c:type:`media_pad_desc`
 119        -  ``source``
 120        -  Pad at the origin of this link.
 121
 122     *  -  struct :c:type:`media_pad_desc`
 123        -  ``sink``
 124        -  Pad at the target of this link.
 125
 126     *  -  __u32
 127        -  ``flags``
 128        -  Link flags, see :ref:`media-link-flag` for more details.
 129
 130     *  -  __u32
 131        -  ``reserved[4]``
 132        -  Reserved for future extensions. Drivers and applications must set
 133           the array to zero.
 134
 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.