Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: MC
   3
   4 .. _media_ioc_g_topology:
   5
   6 **************************
   7 ioctl MEDIA_IOC_G_TOPOLOGY
   8 **************************
   9
  10 Name
  11 ====
  12
  13 MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: MEDIA_IOC_G_TOPOLOGY
  19
  20 ``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)``
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :c:func:`open()`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`media_v2_topology`.
  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 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 123
 124 .. c:type:: media_v2_entity
 125
 126 .. flat-table:: struct media_v2_entity
 127     :header-rows:  0
 128     :stub-columns: 0
 129     :widths: 1 2 8
 130
 131     *  -  __u32
 132        -  ``id``
 133        -  Unique ID for the entity. Do not expect that the ID will
 134           always be the same for each instance of the device. In other words,
 135           do not hardcode entity IDs in an application.
 136
 137     *  -  char
 138        -  ``name``\ [64]
 139        -  Entity name as an UTF-8 NULL-terminated string. This name must be unique
 140           within the media topology.
 141
 142     *  -  __u32
 143        -  ``function``
 144        -  Entity main function, see :ref:`media-entity-functions` for details.
 145
 146     *  -  __u32
 147        -  ``flags``
 148        -  Entity flags, see :ref:`media-entity-flag` for details.
 149           Only valid if ``MEDIA_V2_ENTITY_HAS_FLAGS(media_version)``
 150           returns true. The ``media_version`` is defined in struct
 151           :c:type:`media_device_info` and can be retrieved using
 152           :ref:`MEDIA_IOC_DEVICE_INFO`.
 153
 154     *  -  __u32
 155        -  ``reserved``\ [5]
 156        -  Reserved for future extensions. Drivers and applications must set
 157           this array to zero.
 158
 159 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 160
 161 .. c:type:: media_v2_interface
 162
 163 .. flat-table:: struct media_v2_interface
 164     :header-rows:  0
 165     :stub-columns: 0
 166     :widths: 1 2 8
 167
 168     *  -  __u32
 169        -  ``id``
 170        -  Unique ID for the interface. Do not expect that the ID will
 171           always be the same for each instance of the device. In other words,
 172           do not hardcode interface IDs in an application.
 173
 174     *  -  __u32
 175        -  ``intf_type``
 176        -  Interface type, see :ref:`media-intf-type` for details.
 177
 178     *  -  __u32
 179        -  ``flags``
 180        -  Interface flags. Currently unused.
 181
 182     *  -  __u32
 183        -  ``reserved``\ [9]
 184        -  Reserved for future extensions. Drivers and applications must set
 185           this array to zero.
 186
 187     *  -  struct media_v2_intf_devnode
 188        -  ``devnode``
 189        -  Used only for device node interfaces. See
 190           :c:type:`media_v2_intf_devnode` for details.
 191
 192 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 193
 194 .. c:type:: media_v2_intf_devnode
 195
 196 .. flat-table:: struct media_v2_intf_devnode
 197     :header-rows:  0
 198     :stub-columns: 0
 199     :widths: 1 2 8
 200
 201     *  -  __u32
 202        -  ``major``
 203        -  Device node major number.
 204
 205     *  -  __u32
 206        -  ``minor``
 207        -  Device node minor number.
 208
 209 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 210
 211 .. c:type:: media_v2_pad
 212
 213 .. flat-table:: struct media_v2_pad
 214     :header-rows:  0
 215     :stub-columns: 0
 216     :widths: 1 2 8
 217
 218     *  -  __u32
 219        -  ``id``
 220        -  Unique ID for the pad. Do not expect that the ID will
 221           always be the same for each instance of the device. In other words,
 222           do not hardcode pad IDs in an application.
 223
 224     *  -  __u32
 225        -  ``entity_id``
 226        -  Unique ID for the entity where this pad belongs.
 227
 228     *  -  __u32
 229        -  ``flags``
 230        -  Pad flags, see :ref:`media-pad-flag` for more details.
 231
 232     *  -  __u32
 233        -  ``index``
 234        -  Pad index, starts at 0. Only valid if ``MEDIA_V2_PAD_HAS_INDEX(media_version)``
 235           returns true. The ``media_version`` is defined in struct
 236           :c:type:`media_device_info` and can be retrieved using
 237           :ref:`MEDIA_IOC_DEVICE_INFO`.
 238
 239     *  -  __u32
 240        -  ``reserved``\ [4]
 241        -  Reserved for future extensions. Drivers and applications must set
 242           this array to zero.
 243
 244 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 245
 246 .. c:type:: media_v2_link
 247
 248 .. flat-table:: struct media_v2_link
 249     :header-rows:  0
 250     :stub-columns: 0
 251     :widths: 1 2 8
 252
 253     *  -  __u32
 254        -  ``id``
 255        -  Unique ID for the link. Do not expect that the ID will
 256           always be the same for each instance of the device. In other words,
 257           do not hardcode link IDs in an application.
 258
 259     *  -  __u32
 260        -  ``source_id``
 261        -  On pad to pad links: unique ID for the source pad.
 262
 263           On interface to entity links: unique ID for the interface.
 264
 265     *  -  __u32
 266        -  ``sink_id``
 267        -  On pad to pad links: unique ID for the sink pad.
 268
 269           On interface to entity links: unique ID for the entity.
 270
 271     *  -  __u32
 272        -  ``flags``
 273        -  Link flags, see :ref:`media-link-flag` for more details.
 274
 275     *  -  __u32
 276        -  ``reserved``\ [6]
 277        -  Reserved for future extensions. Drivers and applications must set
 278           this array to zero.
 279
 280 Return Value
 281 ============
 282
 283 On success 0 is returned, on error -1 and the ``errno`` variable is set
 284 appropriately. The generic error codes are described at the
 285 :ref:`Generic Error Codes <gen-errors>` chapter.
 286
 287 ENOSPC
 288     This is returned when either one or more of the num_entities,
 289     num_interfaces, num_links or num_pads are non-zero and are
 290     smaller than the actual number of elements inside the graph. This
 291     may happen if the ``topology_version`` changed when compared to the
 292     last time this ioctl was called. Userspace should usually free the
 293     area for the pointers, zero the struct elements and call this ioctl
 294     again.