Documentation/linux_tv/media/v4l/media-ioc-g-topology.rst

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