Documentation/media/uapi/mediactl/media-ioc-g-topology.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _media_ioc_g_topology:
   4
   5 **************************
   6 ioctl MEDIA_IOC_G_TOPOLOGY
   7 **************************
   8
   9 Name
  10 ====
  11
  12 MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp )
  19     :name: MEDIA_IOC_G_TOPOLOGY
  20
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :ref:`open() <media-func-open>`.
  27
  28 ``argp``
  29
  30
  31 Description
  32 ===========
  33
  34 The typical usage of this ioctl is to call it twice. On the first call,
  35 the structure defined at struct
  36 :c:type:`media_v2_topology` should be zeroed. At
  37 return, if no errors happen, this ioctl will return the
  38 ``topology_version`` and the total number of entities, interfaces, pads
  39 and links.
  40
  41 Before the second call, the userspace should allocate arrays to store
  42 the graph elements that are desired, putting the pointers to them at the
  43 ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the
  44 other values untouched.
  45
  46 If the ``topology_version`` remains the same, the ioctl should fill the
  47 desired arrays with the media graph elements.
  48
  49 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
  50
  51 .. c:type:: media_v2_topology
  52
  53 .. flat-table:: struct media_v2_topology
  54     :header-rows:  0
  55     :stub-columns: 0
  56     :widths: 1 2 8
  57
  58
  59     -  .. row 1
  60
  61        -  __u64
  62
  63        -  ``topology_version``
  64
  65        -  Version of the media graph topology. When the graph is created,
  66           this field starts with zero. Every time a graph element is added
  67           or removed, this field is incremented.
  68
  69     -  .. row 2
  70
  71        -  __u64
  72
  73        -  ``num_entities``
  74
  75        -  Number of entities in the graph
  76
  77     -  .. row 3
  78
  79        -  __u64
  80
  81        -  ``ptr_entities``
  82
  83        -  A pointer to a memory area where the entities array will be
  84           stored, converted to a 64-bits integer. It can be zero. if zero,
  85           the ioctl won't store the entities. It will just update
  86           ``num_entities``
  87
  88     -  .. row 4
  89
  90        -  __u64
  91
  92        -  ``num_interfaces``
  93
  94        -  Number of interfaces in the graph
  95
  96     -  .. row 5
  97
  98        -  __u64
  99
 100        -  ``ptr_interfaces``
 101
 102        -  A pointer to a memory area where the interfaces array will be
 103           stored, converted to a 64-bits integer. It can be zero. if zero,
 104           the ioctl won't store the interfaces. It will just update
 105           ``num_interfaces``
 106
 107     -  .. row 6
 108
 109        -  __u64
 110
 111        -  ``num_pads``
 112
 113        -  Total number of pads in the graph
 114
 115     -  .. row 7
 116
 117        -  __u64
 118
 119        -  ``ptr_pads``
 120
 121        -  A pointer to a memory area where the pads array will be stored,
 122           converted to a 64-bits integer. It can be zero. if zero, the ioctl
 123           won't store the pads. It will just update ``num_pads``
 124
 125     -  .. row 8
 126
 127        -  __u64
 128
 129        -  ``num_links``
 130
 131        -  Total number of data and interface links in the graph
 132
 133     -  .. row 9
 134
 135        -  __u64
 136
 137        -  ``ptr_links``
 138
 139        -  A pointer to a memory area where the links array will be stored,
 140           converted to a 64-bits integer. It can be zero. if zero, the ioctl
 141           won't store the links. It will just update ``num_links``
 142
 143
 144 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 145
 146 .. c:type:: media_v2_entity
 147
 148 .. flat-table:: struct media_v2_entity
 149     :header-rows:  0
 150     :stub-columns: 0
 151     :widths: 1 2 8
 152
 153
 154     -  .. row 1
 155
 156        -  __u32
 157
 158        -  ``id``
 159
 160        -  Unique ID for the entity.
 161
 162     -  .. row 2
 163
 164        -  char
 165
 166        -  ``name``\ [64]
 167
 168        -  Entity name as an UTF-8 NULL-terminated string.
 169
 170     -  .. row 3
 171
 172        -  __u32
 173
 174        -  ``function``
 175
 176        -  Entity main function, see :ref:`media-entity-type` for details.
 177
 178     -  .. row 4
 179
 180        -  __u32
 181
 182        -  ``reserved``\ [12]
 183
 184        -  Reserved for future extensions. Drivers and applications must set
 185           this array to zero.
 186
 187
 188 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 189
 190 .. c:type:: media_v2_interface
 191
 192 .. flat-table:: struct media_v2_interface
 193     :header-rows:  0
 194     :stub-columns: 0
 195     :widths: 1 2 8
 196
 197     -  .. row 1
 198
 199        -  __u32
 200
 201        -  ``id``
 202
 203        -  Unique ID for the interface.
 204
 205     -  .. row 2
 206
 207        -  __u32
 208
 209        -  ``intf_type``
 210
 211        -  Interface type, see :ref:`media-intf-type` for details.
 212
 213     -  .. row 3
 214
 215        -  __u32
 216
 217        -  ``flags``
 218
 219        -  Interface flags. Currently unused.
 220
 221     -  .. row 4
 222
 223        -  __u32
 224
 225        -  ``reserved``\ [9]
 226
 227        -  Reserved for future extensions. Drivers and applications must set
 228           this array to zero.
 229
 230     -  .. row 5
 231
 232        -  struct media_v2_intf_devnode
 233
 234        -  ``devnode``
 235
 236        -  Used only for device node interfaces. See
 237           :c:type:`media_v2_intf_devnode` for details..
 238
 239
 240 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 241
 242 .. c:type:: media_v2_intf_devnode
 243
 244 .. flat-table:: struct media_v2_interface
 245     :header-rows:  0
 246     :stub-columns: 0
 247     :widths: 1 2 8
 248
 249
 250     -  .. row 1
 251
 252        -  __u32
 253
 254        -  ``major``
 255
 256        -  Device node major number.
 257
 258     -  .. row 2
 259
 260        -  __u32
 261
 262        -  ``minor``
 263
 264        -  Device node minor number.
 265
 266
 267 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 268
 269 .. c:type:: media_v2_pad
 270
 271 .. flat-table:: struct media_v2_pad
 272     :header-rows:  0
 273     :stub-columns: 0
 274     :widths: 1 2 8
 275
 276
 277     -  .. row 1
 278
 279        -  __u32
 280
 281        -  ``id``
 282
 283        -  Unique ID for the pad.
 284
 285     -  .. row 2
 286
 287        -  __u32
 288
 289        -  ``entity_id``
 290
 291        -  Unique ID for the entity where this pad belongs.
 292
 293     -  .. row 3
 294
 295        -  __u32
 296
 297        -  ``flags``
 298
 299        -  Pad flags, see :ref:`media-pad-flag` for more details.
 300
 301     -  .. row 4
 302
 303        -  __u32
 304
 305        -  ``reserved``\ [9]
 306
 307        -  Reserved for future extensions. Drivers and applications must set
 308           this array to zero.
 309
 310
 311 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 312
 313 .. c:type:: media_v2_link
 314
 315 .. flat-table:: struct media_v2_pad
 316     :header-rows:  0
 317     :stub-columns: 0
 318     :widths: 1 2 8
 319
 320
 321     -  .. row 1
 322
 323        -  __u32
 324
 325        -  ``id``
 326
 327        -  Unique ID for the pad.
 328
 329     -  .. row 2
 330
 331        -  __u32
 332
 333        -  ``source_id``
 334
 335        -  On pad to pad links: unique ID for the source pad.
 336
 337           On interface to entity links: unique ID for the interface.
 338
 339     -  .. row 3
 340
 341        -  __u32
 342
 343        -  ``sink_id``
 344
 345        -  On pad to pad links: unique ID for the sink pad.
 346
 347           On interface to entity links: unique ID for the entity.
 348
 349     -  .. row 4
 350
 351        -  __u32
 352
 353        -  ``flags``
 354
 355        -  Link flags, see :ref:`media-link-flag` for more details.
 356
 357     -  .. row 5
 358
 359        -  __u32
 360
 361        -  ``reserved``\ [5]
 362
 363        -  Reserved for future extensions. Drivers and applications must set
 364           this array to zero.
 365
 366
 367 Return Value
 368 ============
 369
 370 On success 0 is returned, on error -1 and the ``errno`` variable is set
 371 appropriately. The generic error codes are described at the
 372 :ref:`Generic Error Codes <gen-errors>` chapter.
 373
 374 ENOSPC
 375     This is returned when either one or more of the num_entities,
 376     num_interfaces, num_links or num_pads are non-zero and are
 377     smaller than the actual number of elements inside the graph. This
 378     may happen if the ``topology_version`` changed when compared to the
 379     last time this ioctl was called. Userspace should usually free the
 380     area for the pointers, zero the struct elements and call this ioctl
 381     again.