]>
Commit | Line | Data |
---|---|---|
6494d708 SG |
1 | /* |
2 | * Copyright (c) 2013 Google, Inc | |
3 | * | |
4 | * (C) Copyright 2012 | |
5 | * Pavel Herrmann <morpheus.ibis@gmail.com> | |
6 | * | |
7 | * SPDX-License-Identifier: GPL-2.0+ | |
8 | */ | |
9 | ||
10 | #ifndef _DM_UCLASS_H | |
11 | #define _DM_UCLASS_H | |
12 | ||
40bb637d | 13 | #include <dm/ofnode.h> |
6494d708 | 14 | #include <dm/uclass-id.h> |
42c23dd2 | 15 | #include <linker_lists.h> |
6494d708 SG |
16 | #include <linux/list.h> |
17 | ||
18 | /** | |
19 | * struct uclass - a U-Boot drive class, collecting together similar drivers | |
20 | * | |
21 | * A uclass provides an interface to a particular function, which is | |
22 | * implemented by one or more drivers. Every driver belongs to a uclass even | |
23 | * if it is the only driver in that uclass. An example uclass is GPIO, which | |
24 | * provides the ability to change read inputs, set and clear outputs, etc. | |
25 | * There may be drivers for on-chip SoC GPIO banks, I2C GPIO expanders and | |
26 | * PMIC IO lines, all made available in a unified way through the uclass. | |
27 | * | |
28 | * @priv: Private data for this uclass | |
29 | * @uc_drv: The driver for the uclass itself, not to be confused with a | |
30 | * 'struct driver' | |
f2bc6fc3 | 31 | * @dev_head: List of devices in this uclass (devices are attached to their |
6494d708 SG |
32 | * uclass when their bind method is called) |
33 | * @sibling_node: Next uclass in the linked list of uclasses | |
34 | */ | |
35 | struct uclass { | |
36 | void *priv; | |
37 | struct uclass_driver *uc_drv; | |
38 | struct list_head dev_head; | |
39 | struct list_head sibling_node; | |
40 | }; | |
41 | ||
c57f806b | 42 | struct driver; |
54c5d08a | 43 | struct udevice; |
6494d708 | 44 | |
9cc36a2b SG |
45 | /* Members of this uclass sequence themselves with aliases */ |
46 | #define DM_UC_FLAG_SEQ_ALIAS (1 << 0) | |
47 | ||
6494d708 SG |
48 | /** |
49 | * struct uclass_driver - Driver for the uclass | |
50 | * | |
51 | * A uclass_driver provides a consistent interface to a set of related | |
52 | * drivers. | |
53 | * | |
54 | * @name: Name of uclass driver | |
55 | * @id: ID number of this uclass | |
56 | * @post_bind: Called after a new device is bound to this uclass | |
57 | * @pre_unbind: Called before a device is unbound from this uclass | |
02c07b37 | 58 | * @pre_probe: Called before a new device is probed |
6494d708 SG |
59 | * @post_probe: Called after a new device is probed |
60 | * @pre_remove: Called before a device is removed | |
081f2fcb | 61 | * @child_post_bind: Called after a child is bound to a device in this uclass |
6494d708 SG |
62 | * @init: Called to set up the uclass |
63 | * @destroy: Called to destroy the uclass | |
64 | * @priv_auto_alloc_size: If non-zero this is the size of the private data | |
65 | * to be allocated in the uclass's ->priv pointer. If zero, then the uclass | |
66 | * driver is responsible for allocating any data required. | |
67 | * @per_device_auto_alloc_size: Each device can hold private data owned | |
68 | * by the uclass. If required this will be automatically allocated if this | |
69 | * value is non-zero. | |
5eaed880 PM |
70 | * @per_device_platdata_auto_alloc_size: Each device can hold platform data |
71 | * owned by the uclass as 'dev->uclass_platdata'. If the value is non-zero, | |
72 | * then this will be automatically allocated. | |
dac8db2c SG |
73 | * @per_child_auto_alloc_size: Each child device (of a parent in this |
74 | * uclass) can hold parent data for the device/uclass. This value is only | |
75 | * used as a falback if this member is 0 in the driver. | |
ba8da9dc SG |
76 | * @per_child_platdata_auto_alloc_size: A bus likes to store information about |
77 | * its children. If non-zero this is the size of this data, to be allocated | |
78 | * in the child device's parent_platdata pointer. This value is only used as | |
79 | * a falback if this member is 0 in the driver. | |
6494d708 SG |
80 | * @ops: Uclass operations, providing the consistent interface to devices |
81 | * within the uclass. | |
9cc36a2b | 82 | * @flags: Flags for this uclass (DM_UC_...) |
6494d708 SG |
83 | */ |
84 | struct uclass_driver { | |
85 | const char *name; | |
86 | enum uclass_id id; | |
54c5d08a HS |
87 | int (*post_bind)(struct udevice *dev); |
88 | int (*pre_unbind)(struct udevice *dev); | |
02c07b37 | 89 | int (*pre_probe)(struct udevice *dev); |
54c5d08a HS |
90 | int (*post_probe)(struct udevice *dev); |
91 | int (*pre_remove)(struct udevice *dev); | |
081f2fcb | 92 | int (*child_post_bind)(struct udevice *dev); |
83c7e434 | 93 | int (*child_pre_probe)(struct udevice *dev); |
6494d708 SG |
94 | int (*init)(struct uclass *class); |
95 | int (*destroy)(struct uclass *class); | |
96 | int priv_auto_alloc_size; | |
97 | int per_device_auto_alloc_size; | |
5eaed880 | 98 | int per_device_platdata_auto_alloc_size; |
dac8db2c | 99 | int per_child_auto_alloc_size; |
ba8da9dc | 100 | int per_child_platdata_auto_alloc_size; |
6494d708 | 101 | const void *ops; |
9cc36a2b | 102 | uint32_t flags; |
6494d708 SG |
103 | }; |
104 | ||
105 | /* Declare a new uclass_driver */ | |
106 | #define UCLASS_DRIVER(__name) \ | |
107 | ll_entry_declare(struct uclass_driver, __name, uclass) | |
108 | ||
109 | /** | |
110 | * uclass_get() - Get a uclass based on an ID, creating it if needed | |
111 | * | |
112 | * Every uclass is identified by an ID, a number from 0 to n-1 where n is | |
113 | * the number of uclasses. This function allows looking up a uclass by its | |
114 | * ID. | |
115 | * | |
116 | * @key: ID to look up | |
117 | * @ucp: Returns pointer to uclass (there is only one per ID) | |
118 | * @return 0 if OK, -ve on error | |
119 | */ | |
120 | int uclass_get(enum uclass_id key, struct uclass **ucp); | |
121 | ||
0a5f6f86 SG |
122 | /** |
123 | * uclass_get_name() - Get the name of a uclass driver | |
124 | * | |
125 | * @id: ID to look up | |
126 | * @returns the name of the uclass driver for that ID, or NULL if none | |
127 | */ | |
128 | const char *uclass_get_name(enum uclass_id id); | |
129 | ||
6494d708 SG |
130 | /** |
131 | * uclass_get_device() - Get a uclass device based on an ID and index | |
132 | * | |
f2bc6fc3 SG |
133 | * The device is probed to activate it ready for use. |
134 | * | |
0040b944 | 135 | * @id: ID to look up |
6494d708 | 136 | * @index: Device number within that uclass (0=first) |
f2bc6fc3 | 137 | * @devp: Returns pointer to device (there is only one per for each ID) |
6494d708 SG |
138 | * @return 0 if OK, -ve on error |
139 | */ | |
f2bc6fc3 | 140 | int uclass_get_device(enum uclass_id id, int index, struct udevice **devp); |
6494d708 | 141 | |
b7af1a2d | 142 | /** |
74356d7f | 143 | * uclass_get_device_by_name() - Get a uclass device by its name |
b7af1a2d | 144 | * |
a7b82502 | 145 | * This searches the devices in the uclass for one with the exactly given name. |
b7af1a2d PM |
146 | * |
147 | * The device is probed to activate it ready for use. | |
148 | * | |
149 | * @id: ID to look up | |
150 | * @name: name of a device to get | |
151 | * @devp: Returns pointer to device (the first one with the name) | |
152 | * @return 0 if OK, -ve on error | |
153 | */ | |
154 | int uclass_get_device_by_name(enum uclass_id id, const char *name, | |
155 | struct udevice **devp); | |
156 | ||
5a66a8ff SG |
157 | /** |
158 | * uclass_get_device_by_seq() - Get a uclass device based on an ID and sequence | |
159 | * | |
160 | * If an active device has this sequence it will be returned. If there is no | |
161 | * such device then this will check for a device that is requesting this | |
162 | * sequence. | |
163 | * | |
164 | * The device is probed to activate it ready for use. | |
165 | * | |
166 | * @id: ID to look up | |
167 | * @seq: Sequence number to find (0=first) | |
168 | * @devp: Returns pointer to device (there is only one for each seq) | |
169 | * @return 0 if OK, -ve on error | |
170 | */ | |
171 | int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp); | |
172 | ||
f4cdead2 SG |
173 | /** |
174 | * uclass_get_device_by_of_offset() - Get a uclass device by device tree node | |
175 | * | |
176 | * This searches the devices in the uclass for one attached to the given | |
177 | * device tree node. | |
178 | * | |
179 | * The device is probed to activate it ready for use. | |
180 | * | |
181 | * @id: ID to look up | |
182 | * @node: Device tree offset to search for (if -ve then -ENODEV is returned) | |
183 | * @devp: Returns pointer to device (there is only one for each node) | |
184 | * @return 0 if OK, -ve on error | |
185 | */ | |
186 | int uclass_get_device_by_of_offset(enum uclass_id id, int node, | |
187 | struct udevice **devp); | |
188 | ||
40bb637d SG |
189 | /** |
190 | * uclass_get_device_by_ofnode() - Get a uclass device by device tree node | |
191 | * | |
192 | * This searches the devices in the uclass for one attached to the given | |
193 | * device tree node. | |
194 | * | |
195 | * The device is probed to activate it ready for use. | |
196 | * | |
197 | * @id: ID to look up | |
198 | * @np: Device tree node to search for (if NULL then -ENODEV is returned) | |
199 | * @devp: Returns pointer to device (there is only one for each node) | |
200 | * @return 0 if OK, -ve on error | |
201 | */ | |
202 | int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node, | |
203 | struct udevice **devp); | |
204 | ||
d82ba4c0 SG |
205 | /** |
206 | * uclass_get_device_by_phandle() - Get a uclass device by phandle | |
207 | * | |
208 | * This searches the devices in the uclass for one with the given phandle. | |
209 | * | |
210 | * The device is probed to activate it ready for use. | |
211 | * | |
212 | * @id: uclass ID to look up | |
213 | * @parent: Parent device containing the phandle pointer | |
214 | * @name: Name of property in the parent device node | |
215 | * @devp: Returns pointer to device (there is only one for each node) | |
216 | * @return 0 if OK, -ENOENT if there is no @name present in the node, other | |
217 | * -ve on error | |
218 | */ | |
219 | int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent, | |
220 | const char *name, struct udevice **devp); | |
221 | ||
c57f806b SG |
222 | /** |
223 | * uclass_get_device_by_driver() - Get a uclass device for a driver | |
224 | * | |
225 | * This searches the devices in the uclass for one that uses the given | |
226 | * driver. Use DM_GET_DRIVER(name) for the @drv argument, where 'name' is | |
227 | * the driver name - as used in U_BOOT_DRIVER(name). | |
228 | * | |
229 | * The device is probed to activate it ready for use. | |
230 | * | |
231 | * @id: ID to look up | |
232 | * @drv: Driver to look for | |
233 | * @devp: Returns pointer to the first device with that driver | |
234 | * @return 0 if OK, -ve on error | |
235 | */ | |
236 | int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv, | |
237 | struct udevice **devp); | |
238 | ||
6494d708 SG |
239 | /** |
240 | * uclass_first_device() - Get the first device in a uclass | |
241 | * | |
040b69af SG |
242 | * The device returned is probed if necessary, and ready for use |
243 | * | |
30a570a9 SG |
244 | * This function is useful to start iterating through a list of devices which |
245 | * are functioning correctly and can be probed. | |
246 | * | |
6494d708 | 247 | * @id: Uclass ID to look up |
30a570a9 SG |
248 | * @devp: Returns pointer to the first device in that uclass if no error |
249 | * occurred, or NULL if there is no first device, or an error occurred with | |
250 | * that device. | |
b0675050 | 251 | * @return 0 if OK (found or not found), other -ve on error |
6494d708 | 252 | */ |
54c5d08a | 253 | int uclass_first_device(enum uclass_id id, struct udevice **devp); |
6494d708 | 254 | |
b0675050 SG |
255 | /** |
256 | * uclass_first_device_err() - Get the first device in a uclass | |
257 | * | |
258 | * The device returned is probed if necessary, and ready for use | |
259 | * | |
260 | * @id: Uclass ID to look up | |
261 | * @devp: Returns pointer to the first device in that uclass, or NULL if none | |
262 | * @return 0 if found, -ENODEV if not found, other -ve on error | |
263 | */ | |
264 | int uclass_first_device_err(enum uclass_id id, struct udevice **devp); | |
265 | ||
6494d708 SG |
266 | /** |
267 | * uclass_next_device() - Get the next device in a uclass | |
268 | * | |
040b69af SG |
269 | * The device returned is probed if necessary, and ready for use |
270 | * | |
30a570a9 SG |
271 | * This function is useful to start iterating through a list of devices which |
272 | * are functioning correctly and can be probed. | |
273 | * | |
6494d708 | 274 | * @devp: On entry, pointer to device to lookup. On exit, returns pointer |
30a570a9 SG |
275 | * to the next device in the uclass if no error occurred, or NULL if there is |
276 | * no next device, or an error occurred with that next device. | |
b0675050 | 277 | * @return 0 if OK (found or not found), other -ve on error |
6494d708 | 278 | */ |
54c5d08a | 279 | int uclass_next_device(struct udevice **devp); |
6494d708 | 280 | |
95ce385a SG |
281 | /** |
282 | * uclass_first_device() - Get the first device in a uclass | |
283 | * | |
284 | * The device returned is probed if necessary, and ready for use | |
285 | * | |
286 | * This function is useful to start iterating through a list of devices which | |
287 | * are functioning correctly and can be probed. | |
288 | * | |
289 | * @id: Uclass ID to look up | |
290 | * @devp: Returns pointer to the first device in that uclass, or NULL if there | |
291 | * is no first device | |
292 | * @return 0 if OK (found or not found), other -ve on error. If an error occurs | |
293 | * it is still possible to move to the next device. | |
294 | */ | |
295 | int uclass_first_device_check(enum uclass_id id, struct udevice **devp); | |
296 | ||
297 | /** | |
298 | * uclass_next_device() - Get the next device in a uclass | |
299 | * | |
300 | * The device returned is probed if necessary, and ready for use | |
301 | * | |
302 | * This function is useful to start iterating through a list of devices which | |
303 | * are functioning correctly and can be probed. | |
304 | * | |
305 | * @devp: On entry, pointer to device to lookup. On exit, returns pointer | |
306 | * to the next device in the uclass if any | |
307 | * @return 0 if OK (found or not found), other -ve on error. If an error occurs | |
308 | * it is still possible to move to the next device. | |
309 | */ | |
310 | int uclass_next_device_check(struct udevice **devp); | |
311 | ||
5a66a8ff SG |
312 | /** |
313 | * uclass_resolve_seq() - Resolve a device's sequence number | |
314 | * | |
315 | * On entry dev->seq is -1, and dev->req_seq may be -1 (to allocate a | |
316 | * sequence number automatically, or >= 0 to select a particular number. | |
317 | * If the requested sequence number is in use, then this device will | |
318 | * be allocated another one. | |
319 | * | |
320 | * Note that the device's seq value is not changed by this function. | |
321 | * | |
322 | * @dev: Device for which to allocate sequence number | |
323 | * @return sequence number allocated, or -ve on error | |
324 | */ | |
325 | int uclass_resolve_seq(struct udevice *dev); | |
326 | ||
6494d708 SG |
327 | /** |
328 | * uclass_foreach_dev() - Helper function to iteration through devices | |
329 | * | |
330 | * This creates a for() loop which works through the available devices in | |
331 | * a uclass in order from start to end. | |
332 | * | |
54c5d08a | 333 | * @pos: struct udevice * to hold the current device. Set to NULL when there |
6494d708 | 334 | * are no more devices. |
f2bc6fc3 | 335 | * @uc: uclass to scan |
6494d708 | 336 | */ |
71f1e3f1 MY |
337 | #define uclass_foreach_dev(pos, uc) \ |
338 | list_for_each_entry(pos, &uc->dev_head, uclass_node) | |
6494d708 | 339 | |
7aeac5bc SG |
340 | /** |
341 | * uclass_foreach_dev_safe() - Helper function to safely iteration through devs | |
342 | * | |
343 | * This creates a for() loop which works through the available devices in | |
344 | * a uclass in order from start to end. Inside the loop, it is safe to remove | |
345 | * @pos if required. | |
346 | * | |
347 | * @pos: struct udevice * to hold the current device. Set to NULL when there | |
348 | * are no more devices. | |
349 | * @next: struct udevice * to hold the next next | |
350 | * @uc: uclass to scan | |
351 | */ | |
352 | #define uclass_foreach_dev_safe(pos, next, uc) \ | |
353 | list_for_each_entry_safe(pos, next, &uc->dev_head, uclass_node) | |
354 | ||
6494d708 | 355 | #endif |