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