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.4cm}|p{12.5cm}|
  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        -  __u32
  72
  73        -  ``num_entities``
  74
  75        -  Number of entities in the graph
  76
  77     -  .. row 3
  78
  79        -  __u32
  80
  81        -  ``reserved1``
  82
  83        -  Applications and drivers shall set this to 0.
  84
  85     -  .. row 4
  86
  87        -  __u64
  88
  89        -  ``ptr_entities``
  90
  91        -  A pointer to a memory area where the entities array will be
  92           stored, converted to a 64-bits integer. It can be zero. if zero,
  93           the ioctl won't store the entities. It will just update
  94           ``num_entities``
  95
  96     -  .. row 5
  97
  98        -  __u32
  99
 100        -  ``num_interfaces``
 101
 102        -  Number of interfaces in the graph
 103
 104     -  .. row 6
 105
 106        -  __u32
 107
 108        -  ``reserved2``
 109
 110        -  Applications and drivers shall set this to 0.
 111
 112     -  .. row 7
 113
 114        -  __u64
 115
 116        -  ``ptr_interfaces``
 117
 118        -  A pointer to a memory area where the interfaces array will be
 119           stored, converted to a 64-bits integer. It can be zero. if zero,
 120           the ioctl won't store the interfaces. It will just update
 121           ``num_interfaces``
 122
 123     -  .. row 8
 124
 125        -  __u32
 126
 127        -  ``num_pads``
 128
 129        -  Total number of pads in the graph
 130
 131     -  .. row 9
 132
 133        -  __u32
 134
 135        -  ``reserved3``
 136
 137        -  Applications and drivers shall set this to 0.
 138
 139     -  .. row 10
 140
 141        -  __u64
 142
 143        -  ``ptr_pads``
 144
 145        -  A pointer to a memory area where the pads array will be stored,
 146           converted to a 64-bits integer. It can be zero. if zero, the ioctl
 147           won't store the pads. It will just update ``num_pads``
 148
 149     -  .. row 11
 150
 151        -  __u32
 152
 153        -  ``num_links``
 154
 155        -  Total number of data and interface links in the graph
 156
 157     -  .. row 12
 158
 159        -  __u32
 160
 161        -  ``reserved4``
 162
 163        -  Applications and drivers shall set this to 0.
 164
 165     -  .. row 13
 166
 167        -  __u64
 168
 169        -  ``ptr_links``
 170
 171        -  A pointer to a memory area where the links array will be stored,
 172           converted to a 64-bits integer. It can be zero. if zero, the ioctl
 173           won't store the links. It will just update ``num_links``
 174
 175
 176 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 177
 178 .. c:type:: media_v2_entity
 179
 180 .. flat-table:: struct media_v2_entity
 181     :header-rows:  0
 182     :stub-columns: 0
 183     :widths: 1 2 8
 184
 185
 186     -  .. row 1
 187
 188        -  __u32
 189
 190        -  ``id``
 191
 192        -  Unique ID for the entity.
 193
 194     -  .. row 2
 195
 196        -  char
 197
 198        -  ``name``\ [64]
 199
 200        -  Entity name as an UTF-8 NULL-terminated string.
 201
 202     -  .. row 3
 203
 204        -  __u32
 205
 206        -  ``function``
 207
 208        -  Entity main function, see :ref:`media-entity-functions` for details.
 209
 210     -  .. row 4
 211
 212        -  __u32
 213
 214        -  ``reserved``\ [6]
 215
 216        -  Reserved for future extensions. Drivers and applications must set
 217           this array to zero.
 218
 219
 220 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 221
 222 .. c:type:: media_v2_interface
 223
 224 .. flat-table:: struct media_v2_interface
 225     :header-rows:  0
 226     :stub-columns: 0
 227     :widths: 1 2 8
 228
 229     -  .. row 1
 230
 231        -  __u32
 232
 233        -  ``id``
 234
 235        -  Unique ID for the interface.
 236
 237     -  .. row 2
 238
 239        -  __u32
 240
 241        -  ``intf_type``
 242
 243        -  Interface type, see :ref:`media-intf-type` for details.
 244
 245     -  .. row 3
 246
 247        -  __u32
 248
 249        -  ``flags``
 250
 251        -  Interface flags. Currently unused.
 252
 253     -  .. row 4
 254
 255        -  __u32
 256
 257        -  ``reserved``\ [9]
 258
 259        -  Reserved for future extensions. Drivers and applications must set
 260           this array to zero.
 261
 262     -  .. row 5
 263
 264        -  struct media_v2_intf_devnode
 265
 266        -  ``devnode``
 267
 268        -  Used only for device node interfaces. See
 269           :c:type:`media_v2_intf_devnode` for details..
 270
 271
 272 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 273
 274 .. c:type:: media_v2_intf_devnode
 275
 276 .. flat-table:: struct media_v2_intf_devnode
 277     :header-rows:  0
 278     :stub-columns: 0
 279     :widths: 1 2 8
 280
 281
 282     -  .. row 1
 283
 284        -  __u32
 285
 286        -  ``major``
 287
 288        -  Device node major number.
 289
 290     -  .. row 2
 291
 292        -  __u32
 293
 294        -  ``minor``
 295
 296        -  Device node minor number.
 297
 298
 299 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 300
 301 .. c:type:: media_v2_pad
 302
 303 .. flat-table:: struct media_v2_pad
 304     :header-rows:  0
 305     :stub-columns: 0
 306     :widths: 1 2 8
 307
 308
 309     -  .. row 1
 310
 311        -  __u32
 312
 313        -  ``id``
 314
 315        -  Unique ID for the pad.
 316
 317     -  .. row 2
 318
 319        -  __u32
 320
 321        -  ``entity_id``
 322
 323        -  Unique ID for the entity where this pad belongs.
 324
 325     -  .. row 3
 326
 327        -  __u32
 328
 329        -  ``flags``
 330
 331        -  Pad flags, see :ref:`media-pad-flag` for more details.
 332
 333     -  .. row 4
 334
 335        -  __u32
 336
 337        -  ``reserved``\ [5]
 338
 339        -  Reserved for future extensions. Drivers and applications must set
 340           this array to zero.
 341
 342
 343 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 344
 345 .. c:type:: media_v2_link
 346
 347 .. flat-table:: struct media_v2_link
 348     :header-rows:  0
 349     :stub-columns: 0
 350     :widths: 1 2 8
 351
 352
 353     -  .. row 1
 354
 355        -  __u32
 356
 357        -  ``id``
 358
 359        -  Unique ID for the link.
 360
 361     -  .. row 2
 362
 363        -  __u32
 364
 365        -  ``source_id``
 366
 367        -  On pad to pad links: unique ID for the source pad.
 368
 369           On interface to entity links: unique ID for the interface.
 370
 371     -  .. row 3
 372
 373        -  __u32
 374
 375        -  ``sink_id``
 376
 377        -  On pad to pad links: unique ID for the sink pad.
 378
 379           On interface to entity links: unique ID for the entity.
 380
 381     -  .. row 4
 382
 383        -  __u32
 384
 385        -  ``flags``
 386
 387        -  Link flags, see :ref:`media-link-flag` for more details.
 388
 389     -  .. row 5
 390
 391        -  __u32
 392
 393        -  ``reserved``\ [6]
 394
 395        -  Reserved for future extensions. Drivers and applications must set
 396           this array to zero.
 397
 398
 399 Return Value
 400 ============
 401
 402 On success 0 is returned, on error -1 and the ``errno`` variable is set
 403 appropriately. The generic error codes are described at the
 404 :ref:`Generic Error Codes <gen-errors>` chapter.
 405
 406 ENOSPC
 407     This is returned when either one or more of the num_entities,
 408     num_interfaces, num_links or num_pads are non-zero and are
 409     smaller than the actual number of elements inside the graph. This
 410     may happen if the ``topology_version`` changed when compared to the
 411     last time this ioctl was called. Userspace should usually free the
 412     area for the pointers, zero the struct elements and call this ioctl
 413     again.