Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _media_ioc_enum_entities:
  11
  12 *****************************
  13 ioctl MEDIA_IOC_ENUM_ENTITIES
  14 *****************************
  15
  16 Name
  17 ====
  18
  19 MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp )
  26     :name: MEDIA_IOC_ENUM_ENTITIES
  27
  28
  29 Arguments
  30 =========
  31
  32 ``fd``
  33     File descriptor returned by :ref:`open() <media-func-open>`.
  34
  35 ``argp``
  36     Pointer to struct :c:type:`media_entity_desc`.
  37
  38
  39 Description
  40 ===========
  41
  42 To query the attributes of an entity, applications set the id field of a
  43 struct :c:type:`media_entity_desc` structure and
  44 call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this
  45 structure. The driver fills the rest of the structure or returns an
  46 EINVAL error code when the id is invalid.
  47
  48 .. _media-ent-id-flag-next:
  49
  50 Entities can be enumerated by or'ing the id with the
  51 ``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information
  52 about the entity with the smallest id strictly larger than the requested
  53 one ('next entity'), or the ``EINVAL`` error code if there is none.
  54
  55 Entity IDs can be non-contiguous. Applications must *not* try to
  56 enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing
  57 id's until they get an error.
  58
  59
  60 .. c:type:: media_entity_desc
  61
  62 .. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}|
  63
  64 .. flat-table:: struct media_entity_desc
  65     :header-rows:  0
  66     :stub-columns: 0
  67     :widths: 1 1 1 1 8
  68
  69     *  -  __u32
  70        -  ``id``
  71        -
  72        -
  73        -  Entity ID, set by the application. When the ID is or'ed with
  74           ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns
  75           the first entity with a larger ID. Do not expect that the ID will
  76           always be the same for each instance of the device. In other words,
  77           do not hardcode entity IDs in an application.
  78
  79     *  -  char
  80        -  ``name``\ [32]
  81        -
  82        -
  83        -  Entity name as an UTF-8 NULL-terminated string. This name must be unique
  84           within the media topology.
  85
  86     *  -  __u32
  87        -  ``type``
  88        -
  89        -
  90        -  Entity type, see :ref:`media-entity-functions` for details.
  91
  92     *  -  __u32
  93        -  ``revision``
  94        -
  95        -
  96        -  Entity revision. Always zero (obsolete)
  97
  98     *  -  __u32
  99        -  ``flags``
 100        -
 101        -
 102        -  Entity flags, see :ref:`media-entity-flag` for details.
 103
 104     *  -  __u32
 105        -  ``group_id``
 106        -
 107        -
 108        -  Entity group ID. Always zero (obsolete)
 109
 110     *  -  __u16
 111        -  ``pads``
 112        -
 113        -
 114        -  Number of pads
 115
 116     *  -  __u16
 117        -  ``links``
 118        -
 119        -
 120        -  Total number of outbound links. Inbound links are not counted in
 121           this field.
 122
 123     *  -  __u32
 124        -  ``reserved[4]``
 125        -
 126        -
 127        -  Reserved for future extensions. Drivers and applications must set
 128           the array to zero.
 129
 130     *  -  union
 131
 132     *  -
 133        -  struct
 134        -  ``dev``
 135        -
 136        -  Valid for (sub-)devices that create a single device node.
 137
 138     *  -
 139        -
 140        -  __u32
 141        -  ``major``
 142        -  Device node major number.
 143
 144     *  -
 145        -
 146        -  __u32
 147        -  ``minor``
 148        -  Device node minor number.
 149
 150     *  -
 151        -  __u8
 152        -  ``raw``\ [184]
 153        -
 154        -
 155
 156
 157 Return Value
 158 ============
 159
 160 On success 0 is returned, on error -1 and the ``errno`` variable is set
 161 appropriately. The generic error codes are described at the
 162 :ref:`Generic Error Codes <gen-errors>` chapter.
 163
 164 EINVAL
 165     The struct :c:type:`media_entity_desc` ``id``
 166     references a non-existing entity.