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.
 135
 136     *  -  char
 137        -  ``name``\ [64]
 138        -  Entity name as an UTF-8 NULL-terminated string.
 139
 140     *  -  __u32
 141        -  ``function``
 142        -  Entity main function, see :ref:`media-entity-functions` for details.
 143
 144     *  -  __u32
 145        -  ``reserved``\ [6]
 146        -  Reserved for future extensions. Drivers and applications must set
 147           this array to zero.
 148
 149
 150 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 151
 152 .. c:type:: media_v2_interface
 153
 154 .. flat-table:: struct media_v2_interface
 155     :header-rows:  0
 156     :stub-columns: 0
 157     :widths: 1 2 8
 158
 159     *  -  __u32
 160        -  ``id``
 161        -  Unique ID for the interface.
 162
 163     *  -  __u32
 164        -  ``intf_type``
 165        -  Interface type, see :ref:`media-intf-type` for details.
 166
 167     *  -  __u32
 168        -  ``flags``
 169        -  Interface flags. Currently unused.
 170
 171     *  -  __u32
 172        -  ``reserved``\ [9]
 173        -  Reserved for future extensions. Drivers and applications must set
 174           this array to zero.
 175
 176     *  -  struct media_v2_intf_devnode
 177        -  ``devnode``
 178        -  Used only for device node interfaces. See
 179           :c:type:`media_v2_intf_devnode` for details..
 180
 181
 182 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 183
 184 .. c:type:: media_v2_intf_devnode
 185
 186 .. flat-table:: struct media_v2_intf_devnode
 187     :header-rows:  0
 188     :stub-columns: 0
 189     :widths: 1 2 8
 190
 191     *  -  __u32
 192        -  ``major``
 193        -  Device node major number.
 194
 195     *  -  __u32
 196        -  ``minor``
 197        -  Device node minor number.
 198
 199 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 200
 201 .. c:type:: media_v2_pad
 202
 203 .. flat-table:: struct media_v2_pad
 204     :header-rows:  0
 205     :stub-columns: 0
 206     :widths: 1 2 8
 207
 208     *  -  __u32
 209        -  ``id``
 210        -  Unique ID for the pad.
 211
 212     *  -  __u32
 213        -  ``entity_id``
 214        -  Unique ID for the entity where this pad belongs.
 215
 216     *  -  __u32
 217        -  ``flags``
 218        -  Pad flags, see :ref:`media-pad-flag` for more details.
 219
 220     *  -  __u32
 221        -  ``reserved``\ [5]
 222        -  Reserved for future extensions. Drivers and applications must set
 223           this array to zero.
 224
 225
 226 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 227
 228 .. c:type:: media_v2_link
 229
 230 .. flat-table:: struct media_v2_link
 231     :header-rows:  0
 232     :stub-columns: 0
 233     :widths: 1 2 8
 234
 235     *  -  __u32
 236        -  ``id``
 237        -  Unique ID for the link.
 238
 239     *  -  __u32
 240        -  ``source_id``
 241        -  On pad to pad links: unique ID for the source pad.
 242
 243           On interface to entity links: unique ID for the interface.
 244
 245     *  -  __u32
 246        -  ``sink_id``
 247        -  On pad to pad links: unique ID for the sink pad.
 248
 249           On interface to entity links: unique ID for the entity.
 250
 251     *  -  __u32
 252        -  ``flags``
 253        -  Link flags, see :ref:`media-link-flag` for more details.
 254
 255     *  -  __u32
 256        -  ``reserved``\ [6]
 257        -  Reserved for future extensions. Drivers and applications must set
 258           this array to zero.
 259
 260
 261 Return Value
 262 ============
 263
 264 On success 0 is returned, on error -1 and the ``errno`` variable is set
 265 appropriately. The generic error codes are described at the
 266 :ref:`Generic Error Codes <gen-errors>` chapter.
 267
 268 ENOSPC
 269     This is returned when either one or more of the num_entities,
 270     num_interfaces, num_links or num_pads are non-zero and are
 271     smaller than the actual number of elements inside the graph. This
 272     may happen if the ``topology_version`` changed when compared to the
 273     last time this ioctl was called. Userspace should usually free the
 274     area for the pointers, zero the struct elements and call this ioctl
 275     again.