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     *  -  __u64
  59        -  ``topology_version``
  60        -  Version of the media graph topology. When the graph is created,
  61           this field starts with zero. Every time a graph element is added
  62           or removed, this field is incremented.
  63
  64     *  -  __u32
  65        -  ``num_entities``
  66        -  Number of entities in the graph
  67
  68     *  -  __u32
  69        -  ``reserved1``
  70        -  Applications and drivers shall set this to 0.
  71
  72     *  -  __u64
  73        -  ``ptr_entities``
  74        -  A pointer to a memory area where the entities array will be
  75           stored, converted to a 64-bits integer. It can be zero. if zero,
  76           the ioctl won't store the entities. It will just update
  77           ``num_entities``
  78
  79     *  -  __u32
  80        -  ``num_interfaces``
  81        -  Number of interfaces in the graph
  82
  83     *  -  __u32
  84        -  ``reserved2``
  85        -  Applications and drivers shall set this to 0.
  86
  87     *  -  __u64
  88        -  ``ptr_interfaces``
  89        -  A pointer to a memory area where the interfaces array will be
  90           stored, converted to a 64-bits integer. It can be zero. if zero,
  91           the ioctl won't store the interfaces. It will just update
  92           ``num_interfaces``
  93
  94     *  -  __u32
  95        -  ``num_pads``
  96        -  Total number of pads in the graph
  97
  98     *  -  __u32
  99        -  ``reserved3``
 100        -  Applications and drivers shall set this to 0.
 101
 102     *  -  __u64
 103        -  ``ptr_pads``
 104        -  A pointer to a memory area where the pads array will be stored,
 105           converted to a 64-bits integer. It can be zero. if zero, the ioctl
 106           won't store the pads. It will just update ``num_pads``
 107
 108     *  -  __u32
 109        -  ``num_links``
 110        -  Total number of data and interface links in the graph
 111
 112     *  -  __u32
 113        -  ``reserved4``
 114        -  Applications and drivers shall set this to 0.
 115
 116     *  -  __u64
 117        -  ``ptr_links``
 118        -  A pointer to a memory area where the links array will be stored,
 119           converted to a 64-bits integer. It can be zero. if zero, the ioctl
 120           won't store the links. It will just update ``num_links``
 121
 122
 123 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 124
 125 .. c:type:: media_v2_entity
 126
 127 .. flat-table:: struct media_v2_entity
 128     :header-rows:  0
 129     :stub-columns: 0
 130     :widths: 1 2 8
 131
 132     *  -  __u32
 133        -  ``id``
 134        -  Unique ID for the entity. Do not expect that the ID will
 135           always be the same for each instance of the device. In other words,
 136           do not hardcode entity IDs in an application.
 137
 138     *  -  char
 139        -  ``name``\ [64]
 140        -  Entity name as an UTF-8 NULL-terminated string. This name must be unique
 141           within the media topology.
 142
 143     *  -  __u32
 144        -  ``function``
 145        -  Entity main function, see :ref:`media-entity-functions` for details.
 146
 147     *  -  __u32
 148        -  ``flags``
 149        -  Entity flags, see :ref:`media-entity-flag` for details.
 150           Only valid if ``MEDIA_V2_ENTITY_HAS_FLAGS(media_version)``
 151           returns true. The ``media_version`` is defined in struct
 152           :c:type:`media_device_info` and can be retrieved using
 153           :ref:`MEDIA_IOC_DEVICE_INFO`.
 154
 155     *  -  __u32
 156        -  ``reserved``\ [5]
 157        -  Reserved for future extensions. Drivers and applications must set
 158           this array to zero.
 159
 160
 161 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 162
 163 .. c:type:: media_v2_interface
 164
 165 .. flat-table:: struct media_v2_interface
 166     :header-rows:  0
 167     :stub-columns: 0
 168     :widths: 1 2 8
 169
 170     *  -  __u32
 171        -  ``id``
 172        -  Unique ID for the interface. Do not expect that the ID will
 173           always be the same for each instance of the device. In other words,
 174           do not hardcode interface IDs in an application.
 175
 176     *  -  __u32
 177        -  ``intf_type``
 178        -  Interface type, see :ref:`media-intf-type` for details.
 179
 180     *  -  __u32
 181        -  ``flags``
 182        -  Interface flags. Currently unused.
 183
 184     *  -  __u32
 185        -  ``reserved``\ [9]
 186        -  Reserved for future extensions. Drivers and applications must set
 187           this array to zero.
 188
 189     *  -  struct media_v2_intf_devnode
 190        -  ``devnode``
 191        -  Used only for device node interfaces. See
 192           :c:type:`media_v2_intf_devnode` for details.
 193
 194
 195 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 196
 197 .. c:type:: media_v2_intf_devnode
 198
 199 .. flat-table:: struct media_v2_intf_devnode
 200     :header-rows:  0
 201     :stub-columns: 0
 202     :widths: 1 2 8
 203
 204     *  -  __u32
 205        -  ``major``
 206        -  Device node major number.
 207
 208     *  -  __u32
 209        -  ``minor``
 210        -  Device node minor number.
 211
 212 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 213
 214 .. c:type:: media_v2_pad
 215
 216 .. flat-table:: struct media_v2_pad
 217     :header-rows:  0
 218     :stub-columns: 0
 219     :widths: 1 2 8
 220
 221     *  -  __u32
 222        -  ``id``
 223        -  Unique ID for the pad. Do not expect that the ID will
 224           always be the same for each instance of the device. In other words,
 225           do not hardcode pad IDs in an application.
 226
 227     *  -  __u32
 228        -  ``entity_id``
 229        -  Unique ID for the entity where this pad belongs.
 230
 231     *  -  __u32
 232        -  ``flags``
 233        -  Pad flags, see :ref:`media-pad-flag` for more details.
 234
 235     *  -  __u32
 236        -  ``index``
 237        -  Pad index, starts at 0. Only valid if ``MEDIA_V2_PAD_HAS_INDEX(media_version)``
 238           returns true. The ``media_version`` is defined in struct
 239           :c:type:`media_device_info` and can be retrieved using
 240           :ref:`MEDIA_IOC_DEVICE_INFO`.
 241
 242     *  -  __u32
 243        -  ``reserved``\ [4]
 244        -  Reserved for future extensions. Drivers and applications must set
 245           this array to zero.
 246
 247
 248 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 249
 250 .. c:type:: media_v2_link
 251
 252 .. flat-table:: struct media_v2_link
 253     :header-rows:  0
 254     :stub-columns: 0
 255     :widths: 1 2 8
 256
 257     *  -  __u32
 258        -  ``id``
 259        -  Unique ID for the link. Do not expect that the ID will
 260           always be the same for each instance of the device. In other words,
 261           do not hardcode link IDs in an application.
 262
 263     *  -  __u32
 264        -  ``source_id``
 265        -  On pad to pad links: unique ID for the source pad.
 266
 267           On interface to entity links: unique ID for the interface.
 268
 269     *  -  __u32
 270        -  ``sink_id``
 271        -  On pad to pad links: unique ID for the sink pad.
 272
 273           On interface to entity links: unique ID for the entity.
 274
 275     *  -  __u32
 276        -  ``flags``
 277        -  Link flags, see :ref:`media-link-flag` for more details.
 278
 279     *  -  __u32
 280        -  ``reserved``\ [6]
 281        -  Reserved for future extensions. Drivers and applications must set
 282           this array to zero.
 283
 284
 285 Return Value
 286 ============
 287
 288 On success 0 is returned, on error -1 and the ``errno`` variable is set
 289 appropriately. The generic error codes are described at the
 290 :ref:`Generic Error Codes <gen-errors>` chapter.
 291
 292 ENOSPC
 293     This is returned when either one or more of the num_entities,
 294     num_interfaces, num_links or num_pads are non-zero and are
 295     smaller than the actual number of elements inside the graph. This
 296     may happen if the ``topology_version`` changed when compared to the
 297     last time this ioctl was called. Userspace should usually free the
 298     area for the pointers, zero the struct elements and call this ioctl
 299     again.