0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: MC
0003
0004 .. _media_ioc_enum_entities:
0005
0006 *****************************
0007 ioctl MEDIA_IOC_ENUM_ENTITIES
0008 *****************************
0009
0010 Name
0011 ====
0012
0013 MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: MEDIA_IOC_ENUM_ENTITIES
0019
0020 ``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`media_entity_desc`.
0030
0031 Description
0032 ===========
0033
0034 To query the attributes of an entity, applications set the id field of a
0035 struct :c:type:`media_entity_desc` structure and
0036 call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this
0037 structure. The driver fills the rest of the structure or returns an
0038 EINVAL error code when the id is invalid.
0039
0040 .. _media-ent-id-flag-next:
0041
0042 Entities can be enumerated by or'ing the id with the
0043 ``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information
0044 about the entity with the smallest id strictly larger than the requested
0045 one ('next entity'), or the ``EINVAL`` error code if there is none.
0046
0047 Entity IDs can be non-contiguous. Applications must *not* try to
0048 enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing
0049 id's until they get an error.
0050
0051 .. c:type:: media_entity_desc
0052
0053 .. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{10.6cm}|
0054
0055 .. flat-table:: struct media_entity_desc
0056 :header-rows: 0
0057 :stub-columns: 0
0058 :widths: 2 2 1 8
0059
0060 * - __u32
0061 - ``id``
0062 -
0063 - Entity ID, set by the application. When the ID is or'ed with
0064 ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns
0065 the first entity with a larger ID. Do not expect that the ID will
0066 always be the same for each instance of the device. In other words,
0067 do not hardcode entity IDs in an application.
0068
0069 * - char
0070 - ``name``\ [32]
0071 -
0072 - Entity name as an UTF-8 NULL-terminated string. This name must be unique
0073 within the media topology.
0074
0075 * - __u32
0076 - ``type``
0077 -
0078 - Entity type, see :ref:`media-entity-functions` for details.
0079
0080 * - __u32
0081 - ``revision``
0082 -
0083 - Entity revision. Always zero (obsolete)
0084
0085 * - __u32
0086 - ``flags``
0087 -
0088 - Entity flags, see :ref:`media-entity-flag` for details.
0089
0090 * - __u32
0091 - ``group_id``
0092 -
0093 - Entity group ID. Always zero (obsolete)
0094
0095 * - __u16
0096 - ``pads``
0097 -
0098 - Number of pads
0099
0100 * - __u16
0101 - ``links``
0102 -
0103 - Total number of outbound links. Inbound links are not counted in
0104 this field.
0105
0106 * - __u32
0107 - ``reserved[4]``
0108 -
0109 - Reserved for future extensions. Drivers and applications must set
0110 the array to zero.
0111
0112 * - union {
0113 - (anonymous)
0114
0115 * - struct
0116 - ``dev``
0117 -
0118 - Valid for (sub-)devices that create a single device node.
0119
0120 * -
0121 - __u32
0122 - ``major``
0123 - Device node major number.
0124
0125 * -
0126 - __u32
0127 - ``minor``
0128 - Device node minor number.
0129
0130 * - __u8
0131 - ``raw``\ [184]
0132 -
0133 -
0134 * - }
0135 -
0136
0137 Return Value
0138 ============
0139
0140 On success 0 is returned, on error -1 and the ``errno`` variable is set
0141 appropriately. The generic error codes are described at the
0142 :ref:`Generic Error Codes <gen-errors>` chapter.
0143
0144 EINVAL
0145 The struct :c:type:`media_entity_desc` ``id``
0146 references a non-existing entity.
