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