Documentation/userspace-api/media/mediactl/media-ioc-g-topology.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/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_g_topology:
  11
  12 **************************
  13 ioctl MEDIA_IOC_G_TOPOLOGY
  14 **************************
  15
  16 Name
  17 ====
  18
  19 MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp )
  26     :name: MEDIA_IOC_G_TOPOLOGY
  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_v2_topology`.
  37
  38
  39 Description
  40 ===========
  41
  42 The typical usage of this ioctl is to call it twice. On the first call,
  43 the structure defined at struct
  44 :c:type:`media_v2_topology` should be zeroed. At
  45 return, if no errors happen, this ioctl will return the
  46 ``topology_version`` and the total number of entities, interfaces, pads
  47 and links.
  48
  49 Before the second call, the userspace should allocate arrays to store
  50 the graph elements that are desired, putting the pointers to them at the
  51 ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the
  52 other values untouched.
  53
  54 If the ``topology_version`` remains the same, the ioctl should fill the
  55 desired arrays with the media graph elements.
  56
  57 .. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.5cm}|
  58
  59 .. c:type:: media_v2_topology
  60
  61 .. flat-table:: struct media_v2_topology
  62     :header-rows:  0
  63     :stub-columns: 0
  64     :widths: 1 2 8
  65
  66     *  -  __u64
  67        -  ``topology_version``
  68        -  Version of the media graph topology. When the graph is created,
  69           this field starts with zero. Every time a graph element is added
  70           or removed, this field is incremented.
  71
  72     *  -  __u32
  73        -  ``num_entities``
  74        -  Number of entities in the graph
  75
  76     *  -  __u32
  77        -  ``reserved1``
  78        -  Applications and drivers shall set this to 0.
  79
  80     *  -  __u64
  81        -  ``ptr_entities``
  82        -  A pointer to a memory area where the entities array will be
  83           stored, converted to a 64-bits integer. It can be zero. if zero,
  84           the ioctl won't store the entities. It will just update
  85           ``num_entities``
  86
  87     *  -  __u32
  88        -  ``num_interfaces``
  89        -  Number of interfaces in the graph
  90
  91     *  -  __u32
  92        -  ``reserved2``
  93        -  Applications and drivers shall set this to 0.
  94
  95     *  -  __u64
  96        -  ``ptr_interfaces``
  97        -  A pointer to a memory area where the interfaces array will be
  98           stored, converted to a 64-bits integer. It can be zero. if zero,
  99           the ioctl won't store the interfaces. It will just update
 100           ``num_interfaces``
 101
 102     *  -  __u32
 103        -  ``num_pads``
 104        -  Total number of pads in the graph
 105
 106     *  -  __u32
 107        -  ``reserved3``
 108        -  Applications and drivers shall set this to 0.
 109
 110     *  -  __u64
 111        -  ``ptr_pads``
 112        -  A pointer to a memory area where the pads array will be stored,
 113           converted to a 64-bits integer. It can be zero. if zero, the ioctl
 114           won't store the pads. It will just update ``num_pads``
 115
 116     *  -  __u32
 117        -  ``num_links``
 118        -  Total number of data and interface links in the graph
 119
 120     *  -  __u32
 121        -  ``reserved4``
 122        -  Applications and drivers shall set this to 0.
 123
 124     *  -  __u64
 125        -  ``ptr_links``
 126        -  A pointer to a memory area where the links array will be stored,
 127           converted to a 64-bits integer. It can be zero. if zero, the ioctl
 128           won't store the links. It will just update ``num_links``
 129
 130
 131 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 132
 133 .. c:type:: media_v2_entity
 134
 135 .. flat-table:: struct media_v2_entity
 136     :header-rows:  0
 137     :stub-columns: 0
 138     :widths: 1 2 8
 139
 140     *  -  __u32
 141        -  ``id``
 142        -  Unique ID for the entity. Do not expect that the ID will
 143           always be the same for each instance of the device. In other words,
 144           do not hardcode entity IDs in an application.
 145
 146     *  -  char
 147        -  ``name``\ [64]
 148        -  Entity name as an UTF-8 NULL-terminated string. This name must be unique
 149           within the media topology.
 150
 151     *  -  __u32
 152        -  ``function``
 153        -  Entity main function, see :ref:`media-entity-functions` for details.
 154
 155     *  -  __u32
 156        -  ``flags``
 157        -  Entity flags, see :ref:`media-entity-flag` for details.
 158           Only valid if ``MEDIA_V2_ENTITY_HAS_FLAGS(media_version)``
 159           returns true. The ``media_version`` is defined in struct
 160           :c:type:`media_device_info` and can be retrieved using
 161           :ref:`MEDIA_IOC_DEVICE_INFO`.
 162
 163     *  -  __u32
 164        -  ``reserved``\ [5]
 165        -  Reserved for future extensions. Drivers and applications must set
 166           this array to zero.
 167
 168
 169 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 170
 171 .. c:type:: media_v2_interface
 172
 173 .. flat-table:: struct media_v2_interface
 174     :header-rows:  0
 175     :stub-columns: 0
 176     :widths: 1 2 8
 177
 178     *  -  __u32
 179        -  ``id``
 180        -  Unique ID for the interface. Do not expect that the ID will
 181           always be the same for each instance of the device. In other words,
 182           do not hardcode interface IDs in an application.
 183
 184     *  -  __u32
 185        -  ``intf_type``
 186        -  Interface type, see :ref:`media-intf-type` for details.
 187
 188     *  -  __u32
 189        -  ``flags``
 190        -  Interface flags. Currently unused.
 191
 192     *  -  __u32
 193        -  ``reserved``\ [9]
 194        -  Reserved for future extensions. Drivers and applications must set
 195           this array to zero.
 196
 197     *  -  struct media_v2_intf_devnode
 198        -  ``devnode``
 199        -  Used only for device node interfaces. See
 200           :c:type:`media_v2_intf_devnode` for details.
 201
 202
 203 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 204
 205 .. c:type:: media_v2_intf_devnode
 206
 207 .. flat-table:: struct media_v2_intf_devnode
 208     :header-rows:  0
 209     :stub-columns: 0
 210     :widths: 1 2 8
 211
 212     *  -  __u32
 213        -  ``major``
 214        -  Device node major number.
 215
 216     *  -  __u32
 217        -  ``minor``
 218        -  Device node minor number.
 219
 220 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 221
 222 .. c:type:: media_v2_pad
 223
 224 .. flat-table:: struct media_v2_pad
 225     :header-rows:  0
 226     :stub-columns: 0
 227     :widths: 1 2 8
 228
 229     *  -  __u32
 230        -  ``id``
 231        -  Unique ID for the pad. Do not expect that the ID will
 232           always be the same for each instance of the device. In other words,
 233           do not hardcode pad IDs in an application.
 234
 235     *  -  __u32
 236        -  ``entity_id``
 237        -  Unique ID for the entity where this pad belongs.
 238
 239     *  -  __u32
 240        -  ``flags``
 241        -  Pad flags, see :ref:`media-pad-flag` for more details.
 242
 243     *  -  __u32
 244        -  ``index``
 245        -  Pad index, starts at 0. Only valid if ``MEDIA_V2_PAD_HAS_INDEX(media_version)``
 246           returns true. The ``media_version`` is defined in struct
 247           :c:type:`media_device_info` and can be retrieved using
 248           :ref:`MEDIA_IOC_DEVICE_INFO`.
 249
 250     *  -  __u32
 251        -  ``reserved``\ [4]
 252        -  Reserved for future extensions. Drivers and applications must set
 253           this array to zero.
 254
 255
 256 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 257
 258 .. c:type:: media_v2_link
 259
 260 .. flat-table:: struct media_v2_link
 261     :header-rows:  0
 262     :stub-columns: 0
 263     :widths: 1 2 8
 264
 265     *  -  __u32
 266        -  ``id``
 267        -  Unique ID for the link. Do not expect that the ID will
 268           always be the same for each instance of the device. In other words,
 269           do not hardcode link IDs in an application.
 270
 271     *  -  __u32
 272        -  ``source_id``
 273        -  On pad to pad links: unique ID for the source pad.
 274
 275           On interface to entity links: unique ID for the interface.
 276
 277     *  -  __u32
 278        -  ``sink_id``
 279        -  On pad to pad links: unique ID for the sink pad.
 280
 281           On interface to entity links: unique ID for the entity.
 282
 283     *  -  __u32
 284        -  ``flags``
 285        -  Link flags, see :ref:`media-link-flag` for more details.
 286
 287     *  -  __u32
 288        -  ``reserved``\ [6]
 289        -  Reserved for future extensions. Drivers and applications must set
 290           this array to zero.
 291
 292
 293 Return Value
 294 ============
 295
 296 On success 0 is returned, on error -1 and the ``errno`` variable is set
 297 appropriately. The generic error codes are described at the
 298 :ref:`Generic Error Codes <gen-errors>` chapter.
 299
 300 ENOSPC
 301     This is returned when either one or more of the num_entities,
 302     num_interfaces, num_links or num_pads are non-zero and are
 303     smaller than the actual number of elements inside the graph. This
 304     may happen if the ``topology_version`` changed when compared to the
 305     last time this ioctl was called. Userspace should usually free the
 306     area for the pointers, zero the struct elements and call this ioctl
 307     again.