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