Commit | Line | Data |
---|---|---|
82559ac0 MCC |
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 | ||
d2c68150 | 10 | .. _media_ioc_enum_entities: |
5377d91f MH |
11 | |
12 | ***************************** | |
13 | ioctl MEDIA_IOC_ENUM_ENTITIES | |
14 | ***************************** | |
15 | ||
15e7d615 | 16 | Name |
586027ce | 17 | ==== |
5377d91f | 18 | |
586027ce | 19 | MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties |
5377d91f | 20 | |
15e7d615 MCC |
21 | |
22 | Synopsis | |
5377d91f MH |
23 | ======== |
24 | ||
5ccbb182 MCC |
25 | .. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp ) |
26 | :name: MEDIA_IOC_ENUM_ENTITIES | |
5377d91f | 27 | |
586027ce | 28 | |
15e7d615 | 29 | Arguments |
5377d91f MH |
30 | ========= |
31 | ||
32 | ``fd`` | |
33 | File descriptor returned by :ref:`open() <media-func-open>`. | |
34 | ||
5377d91f | 35 | ``argp`` |
b4ae675d | 36 | Pointer to struct :c:type:`media_entity_desc`. |
5377d91f MH |
37 | |
38 | ||
15e7d615 | 39 | Description |
5377d91f MH |
40 | =========== |
41 | ||
42 | To query the attributes of an entity, applications set the id field of a | |
e8be7e97 | 43 | struct :c:type:`media_entity_desc` structure and |
5377d91f MH |
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 | ||
d2c68150 MCC |
48 | .. _media-ent-id-flag-next: |
49 | ||
5377d91f MH |
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 | |
cdb4af0f | 53 | one ('next entity'), or the ``EINVAL`` error code if there is none. |
5377d91f MH |
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 | ||
e8be7e97 | 60 | .. c:type:: media_entity_desc |
5377d91f | 61 | |
1367f4ee | 62 | .. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}| |
5bd4bb78 | 63 | |
5377d91f MH |
64 | .. flat-table:: struct media_entity_desc |
65 | :header-rows: 0 | |
66 | :stub-columns: 0 | |
218fc9f2 | 67 | :widths: 2 2 1 8 |
5377d91f | 68 | |
8c4fe248 | 69 | * - __u32 |
5377d91f | 70 | - ``id`` |
0579e6e3 | 71 | - |
8601494e | 72 | - Entity ID, set by the application. When the ID is or'ed with |
0579e6e3 | 73 | ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns |
8601494e HV |
74 | the first entity with a larger ID. Do not expect that the ID will |
75 | always be the same for each instance of the device. In other words, | |
76 | do not hardcode entity IDs in an application. | |
5377d91f | 77 | |
8c4fe248 | 78 | * - char |
8968da9b | 79 | - ``name``\ [32] |
0579e6e3 | 80 | - |
8601494e HV |
81 | - Entity name as an UTF-8 NULL-terminated string. This name must be unique |
82 | within the media topology. | |
5377d91f | 83 | |
8c4fe248 | 84 | * - __u32 |
5377d91f | 85 | - ``type`` |
0579e6e3 | 86 | - |
cccc41fd | 87 | - Entity type, see :ref:`media-entity-functions` for details. |
5377d91f | 88 | |
8c4fe248 | 89 | * - __u32 |
5377d91f | 90 | - ``revision`` |
0579e6e3 | 91 | - |
5377d91f MH |
92 | - Entity revision. Always zero (obsolete) |
93 | ||
8c4fe248 | 94 | * - __u32 |
5377d91f | 95 | - ``flags`` |
0579e6e3 | 96 | - |
5377d91f MH |
97 | - Entity flags, see :ref:`media-entity-flag` for details. |
98 | ||
8c4fe248 | 99 | * - __u32 |
5377d91f | 100 | - ``group_id`` |
0579e6e3 | 101 | - |
5377d91f MH |
102 | - Entity group ID. Always zero (obsolete) |
103 | ||
8c4fe248 | 104 | * - __u16 |
5377d91f | 105 | - ``pads`` |
0579e6e3 | 106 | - |
5377d91f MH |
107 | - Number of pads |
108 | ||
8c4fe248 | 109 | * - __u16 |
5377d91f | 110 | - ``links`` |
0579e6e3 | 111 | - |
5377d91f | 112 | - Total number of outbound links. Inbound links are not counted in |
0579e6e3 | 113 | this field. |
5377d91f | 114 | |
8c4fe248 | 115 | * - __u32 |
84694edc | 116 | - ``reserved[4]`` |
84694edc | 117 | - |
84694edc HV |
118 | - Reserved for future extensions. Drivers and applications must set |
119 | the array to zero. | |
5377d91f | 120 | |
218fc9f2 HV |
121 | * - union { |
122 | - (anonymous) | |
84694edc | 123 | |
218fc9f2 | 124 | * - struct |
5377d91f | 125 | - ``dev`` |
0579e6e3 | 126 | - |
5377d91f MH |
127 | - Valid for (sub-)devices that create a single device node. |
128 | ||
8c4fe248 | 129 | * - |
5377d91f | 130 | - __u32 |
5377d91f | 131 | - ``major`` |
5377d91f MH |
132 | - Device node major number. |
133 | ||
8c4fe248 | 134 | * - |
5377d91f | 135 | - __u32 |
5377d91f | 136 | - ``minor`` |
5377d91f MH |
137 | - Device node minor number. |
138 | ||
218fc9f2 | 139 | * - __u8 |
8968da9b | 140 | - ``raw``\ [184] |
0579e6e3 MCC |
141 | - |
142 | - | |
218fc9f2 HV |
143 | * - } |
144 | - | |
5377d91f MH |
145 | |
146 | ||
15e7d615 | 147 | Return Value |
5377d91f MH |
148 | ============ |
149 | ||
150 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
151 | appropriately. The generic error codes are described at the | |
152 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
153 | ||
154 | EINVAL | |
e8be7e97 | 155 | The struct :c:type:`media_entity_desc` ``id`` |
5377d91f | 156 | references a non-existing entity. |