1*4882a593Smuzhiyun.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2*4882a593Smuzhiyun.. c:namespace:: MC 3*4882a593Smuzhiyun 4*4882a593Smuzhiyun.. _media_ioc_enum_entities: 5*4882a593Smuzhiyun 6*4882a593Smuzhiyun***************************** 7*4882a593Smuzhiyunioctl MEDIA_IOC_ENUM_ENTITIES 8*4882a593Smuzhiyun***************************** 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunName 11*4882a593Smuzhiyun==== 12*4882a593Smuzhiyun 13*4882a593SmuzhiyunMEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties 14*4882a593Smuzhiyun 15*4882a593SmuzhiyunSynopsis 16*4882a593Smuzhiyun======== 17*4882a593Smuzhiyun 18*4882a593Smuzhiyun.. c:macro:: MEDIA_IOC_ENUM_ENTITIES 19*4882a593Smuzhiyun 20*4882a593Smuzhiyun``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)`` 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunArguments 23*4882a593Smuzhiyun========= 24*4882a593Smuzhiyun 25*4882a593Smuzhiyun``fd`` 26*4882a593Smuzhiyun File descriptor returned by :c:func:`open()`. 27*4882a593Smuzhiyun 28*4882a593Smuzhiyun``argp`` 29*4882a593Smuzhiyun Pointer to struct :c:type:`media_entity_desc`. 30*4882a593Smuzhiyun 31*4882a593SmuzhiyunDescription 32*4882a593Smuzhiyun=========== 33*4882a593Smuzhiyun 34*4882a593SmuzhiyunTo query the attributes of an entity, applications set the id field of a 35*4882a593Smuzhiyunstruct :c:type:`media_entity_desc` structure and 36*4882a593Smuzhiyuncall the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this 37*4882a593Smuzhiyunstructure. The driver fills the rest of the structure or returns an 38*4882a593SmuzhiyunEINVAL error code when the id is invalid. 39*4882a593Smuzhiyun 40*4882a593Smuzhiyun.. _media-ent-id-flag-next: 41*4882a593Smuzhiyun 42*4882a593SmuzhiyunEntities can be enumerated by or'ing the id with the 43*4882a593Smuzhiyun``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information 44*4882a593Smuzhiyunabout the entity with the smallest id strictly larger than the requested 45*4882a593Smuzhiyunone ('next entity'), or the ``EINVAL`` error code if there is none. 46*4882a593Smuzhiyun 47*4882a593SmuzhiyunEntity IDs can be non-contiguous. Applications must *not* try to 48*4882a593Smuzhiyunenumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing 49*4882a593Smuzhiyunid's until they get an error. 50*4882a593Smuzhiyun 51*4882a593Smuzhiyun.. c:type:: media_entity_desc 52*4882a593Smuzhiyun 53*4882a593Smuzhiyun.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}| 54*4882a593Smuzhiyun 55*4882a593Smuzhiyun.. flat-table:: struct media_entity_desc 56*4882a593Smuzhiyun :header-rows: 0 57*4882a593Smuzhiyun :stub-columns: 0 58*4882a593Smuzhiyun :widths: 2 2 1 8 59*4882a593Smuzhiyun 60*4882a593Smuzhiyun * - __u32 61*4882a593Smuzhiyun - ``id`` 62*4882a593Smuzhiyun - 63*4882a593Smuzhiyun - Entity ID, set by the application. When the ID is or'ed with 64*4882a593Smuzhiyun ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns 65*4882a593Smuzhiyun the first entity with a larger ID. Do not expect that the ID will 66*4882a593Smuzhiyun always be the same for each instance of the device. In other words, 67*4882a593Smuzhiyun do not hardcode entity IDs in an application. 68*4882a593Smuzhiyun 69*4882a593Smuzhiyun * - char 70*4882a593Smuzhiyun - ``name``\ [32] 71*4882a593Smuzhiyun - 72*4882a593Smuzhiyun - Entity name as an UTF-8 NULL-terminated string. This name must be unique 73*4882a593Smuzhiyun within the media topology. 74*4882a593Smuzhiyun 75*4882a593Smuzhiyun * - __u32 76*4882a593Smuzhiyun - ``type`` 77*4882a593Smuzhiyun - 78*4882a593Smuzhiyun - Entity type, see :ref:`media-entity-functions` for details. 79*4882a593Smuzhiyun 80*4882a593Smuzhiyun * - __u32 81*4882a593Smuzhiyun - ``revision`` 82*4882a593Smuzhiyun - 83*4882a593Smuzhiyun - Entity revision. Always zero (obsolete) 84*4882a593Smuzhiyun 85*4882a593Smuzhiyun * - __u32 86*4882a593Smuzhiyun - ``flags`` 87*4882a593Smuzhiyun - 88*4882a593Smuzhiyun - Entity flags, see :ref:`media-entity-flag` for details. 89*4882a593Smuzhiyun 90*4882a593Smuzhiyun * - __u32 91*4882a593Smuzhiyun - ``group_id`` 92*4882a593Smuzhiyun - 93*4882a593Smuzhiyun - Entity group ID. Always zero (obsolete) 94*4882a593Smuzhiyun 95*4882a593Smuzhiyun * - __u16 96*4882a593Smuzhiyun - ``pads`` 97*4882a593Smuzhiyun - 98*4882a593Smuzhiyun - Number of pads 99*4882a593Smuzhiyun 100*4882a593Smuzhiyun * - __u16 101*4882a593Smuzhiyun - ``links`` 102*4882a593Smuzhiyun - 103*4882a593Smuzhiyun - Total number of outbound links. Inbound links are not counted in 104*4882a593Smuzhiyun this field. 105*4882a593Smuzhiyun 106*4882a593Smuzhiyun * - __u32 107*4882a593Smuzhiyun - ``reserved[4]`` 108*4882a593Smuzhiyun - 109*4882a593Smuzhiyun - Reserved for future extensions. Drivers and applications must set 110*4882a593Smuzhiyun the array to zero. 111*4882a593Smuzhiyun 112*4882a593Smuzhiyun * - union { 113*4882a593Smuzhiyun - (anonymous) 114*4882a593Smuzhiyun 115*4882a593Smuzhiyun * - struct 116*4882a593Smuzhiyun - ``dev`` 117*4882a593Smuzhiyun - 118*4882a593Smuzhiyun - Valid for (sub-)devices that create a single device node. 119*4882a593Smuzhiyun 120*4882a593Smuzhiyun * - 121*4882a593Smuzhiyun - __u32 122*4882a593Smuzhiyun - ``major`` 123*4882a593Smuzhiyun - Device node major number. 124*4882a593Smuzhiyun 125*4882a593Smuzhiyun * - 126*4882a593Smuzhiyun - __u32 127*4882a593Smuzhiyun - ``minor`` 128*4882a593Smuzhiyun - Device node minor number. 129*4882a593Smuzhiyun 130*4882a593Smuzhiyun * - __u8 131*4882a593Smuzhiyun - ``raw``\ [184] 132*4882a593Smuzhiyun - 133*4882a593Smuzhiyun - 134*4882a593Smuzhiyun * - } 135*4882a593Smuzhiyun - 136*4882a593Smuzhiyun 137*4882a593SmuzhiyunReturn Value 138*4882a593Smuzhiyun============ 139*4882a593Smuzhiyun 140*4882a593SmuzhiyunOn success 0 is returned, on error -1 and the ``errno`` variable is set 141*4882a593Smuzhiyunappropriately. The generic error codes are described at the 142*4882a593Smuzhiyun:ref:`Generic Error Codes <gen-errors>` chapter. 143*4882a593Smuzhiyun 144*4882a593SmuzhiyunEINVAL 145*4882a593Smuzhiyun The struct :c:type:`media_entity_desc` ``id`` 146*4882a593Smuzhiyun references a non-existing entity. 147