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