]>
Commit | Line | Data |
---|---|---|
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 | ||
13 | #include <dm/ofnode.h> | |
14 | #include <dm/uclass-id.h> | |
15 | #include <linker_lists.h> | |
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' | |
31 | * @dev_head: List of devices in this uclass (devices are attached to their | |
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 | ||
42 | struct driver; | |
43 | struct udevice; | |
44 | ||
45 | /* Members of this uclass sequence themselves with aliases */ | |
46 | #define DM_UC_FLAG_SEQ_ALIAS (1 << 0) | |
47 | ||
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 | |
58 | * @pre_probe: Called before a new device is probed | |
59 | * @post_probe: Called after a new device is probed | |
60 | * @pre_remove: Called before a device is removed | |
61 | * @child_post_bind: Called after a child is bound to a device in this uclass | |
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. | |
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. | |
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 fallback if this member is 0 in the driver. | |
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 fallback if this member is 0 in the driver. | |
80 | * @ops: Uclass operations, providing the consistent interface to devices | |
81 | * within the uclass. | |
82 | * @flags: Flags for this uclass (DM_UC_...) | |
83 | */ | |
84 | struct uclass_driver { | |
85 | const char *name; | |
86 | enum uclass_id id; | |
87 | int (*post_bind)(struct udevice *dev); | |
88 | int (*pre_unbind)(struct udevice *dev); | |
89 | int (*pre_probe)(struct udevice *dev); | |
90 | int (*post_probe)(struct udevice *dev); | |
91 | int (*pre_remove)(struct udevice *dev); | |
92 | int (*child_post_bind)(struct udevice *dev); | |
93 | int (*child_pre_probe)(struct udevice *dev); | |
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; | |
98 | int per_device_platdata_auto_alloc_size; | |
99 | int per_child_auto_alloc_size; | |
100 | int per_child_platdata_auto_alloc_size; | |
101 | const void *ops; | |
102 | uint32_t flags; | |
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 | ||
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 | ||
130 | /** | |
131 | * uclass_get_by_name() - Look up a uclass by its driver name | |
132 | * | |
133 | * @name: Name to look up | |
134 | * @returns the associated uclass ID, or UCLASS_INVALID if not found | |
135 | */ | |
136 | enum uclass_id uclass_get_by_name(const char *name); | |
137 | ||
138 | /** | |
139 | * uclass_get_device() - Get a uclass device based on an ID and index | |
140 | * | |
141 | * The device is probed to activate it ready for use. | |
142 | * | |
143 | * @id: ID to look up | |
144 | * @index: Device number within that uclass (0=first) | |
145 | * @devp: Returns pointer to device (there is only one per for each ID) | |
146 | * @return 0 if OK, -ve on error | |
147 | */ | |
148 | int uclass_get_device(enum uclass_id id, int index, struct udevice **devp); | |
149 | ||
150 | /** | |
151 | * uclass_get_device_by_name() - Get a uclass device by its name | |
152 | * | |
153 | * This searches the devices in the uclass for one with the exactly given name. | |
154 | * | |
155 | * The device is probed to activate it ready for use. | |
156 | * | |
157 | * @id: ID to look up | |
158 | * @name: name of a device to get | |
159 | * @devp: Returns pointer to device (the first one with the name) | |
160 | * @return 0 if OK, -ve on error | |
161 | */ | |
162 | int uclass_get_device_by_name(enum uclass_id id, const char *name, | |
163 | struct udevice **devp); | |
164 | ||
165 | /** | |
166 | * uclass_get_device_by_seq() - Get a uclass device based on an ID and sequence | |
167 | * | |
168 | * If an active device has this sequence it will be returned. If there is no | |
169 | * such device then this will check for a device that is requesting this | |
170 | * sequence. | |
171 | * | |
172 | * The device is probed to activate it ready for use. | |
173 | * | |
174 | * @id: ID to look up | |
175 | * @seq: Sequence number to find (0=first) | |
176 | * @devp: Returns pointer to device (there is only one for each seq) | |
177 | * @return 0 if OK, -ve on error | |
178 | */ | |
179 | int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp); | |
180 | ||
181 | /** | |
182 | * uclass_get_device_by_of_offset() - Get a uclass device by device tree node | |
183 | * | |
184 | * This searches the devices in the uclass for one attached to the given | |
185 | * device tree node. | |
186 | * | |
187 | * The device is probed to activate it ready for use. | |
188 | * | |
189 | * @id: ID to look up | |
190 | * @node: Device tree offset to search for (if -ve then -ENODEV is returned) | |
191 | * @devp: Returns pointer to device (there is only one for each node) | |
192 | * @return 0 if OK, -ve on error | |
193 | */ | |
194 | int uclass_get_device_by_of_offset(enum uclass_id id, int node, | |
195 | struct udevice **devp); | |
196 | ||
197 | /** | |
198 | * uclass_get_device_by_ofnode() - Get a uclass device by device tree node | |
199 | * | |
200 | * This searches the devices in the uclass for one attached to the given | |
201 | * device tree node. | |
202 | * | |
203 | * The device is probed to activate it ready for use. | |
204 | * | |
205 | * @id: ID to look up | |
206 | * @np: Device tree node to search for (if NULL then -ENODEV is returned) | |
207 | * @devp: Returns pointer to device (there is only one for each node) | |
208 | * @return 0 if OK, -ve on error | |
209 | */ | |
210 | int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node, | |
211 | struct udevice **devp); | |
212 | ||
213 | /** | |
214 | * uclass_get_device_by_phandle() - Get a uclass device by phandle | |
215 | * | |
216 | * This searches the devices in the uclass for one with the given phandle. | |
217 | * | |
218 | * The device is probed to activate it ready for use. | |
219 | * | |
220 | * @id: uclass ID to look up | |
221 | * @parent: Parent device containing the phandle pointer | |
222 | * @name: Name of property in the parent device node | |
223 | * @devp: Returns pointer to device (there is only one for each node) | |
224 | * @return 0 if OK, -ENOENT if there is no @name present in the node, other | |
225 | * -ve on error | |
226 | */ | |
227 | int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent, | |
228 | const char *name, struct udevice **devp); | |
229 | ||
230 | /** | |
231 | * uclass_get_device_by_driver() - Get a uclass device for a driver | |
232 | * | |
233 | * This searches the devices in the uclass for one that uses the given | |
234 | * driver. Use DM_GET_DRIVER(name) for the @drv argument, where 'name' is | |
235 | * the driver name - as used in U_BOOT_DRIVER(name). | |
236 | * | |
237 | * The device is probed to activate it ready for use. | |
238 | * | |
239 | * @id: ID to look up | |
240 | * @drv: Driver to look for | |
241 | * @devp: Returns pointer to the first device with that driver | |
242 | * @return 0 if OK, -ve on error | |
243 | */ | |
244 | int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv, | |
245 | struct udevice **devp); | |
246 | ||
247 | /** | |
248 | * uclass_first_device() - Get the first device in a uclass | |
249 | * | |
250 | * The device returned is probed if necessary, and ready for use | |
251 | * | |
252 | * This function is useful to start iterating through a list of devices which | |
253 | * are functioning correctly and can be probed. | |
254 | * | |
255 | * @id: Uclass ID to look up | |
256 | * @devp: Returns pointer to the first device in that uclass if no error | |
257 | * occurred, or NULL if there is no first device, or an error occurred with | |
258 | * that device. | |
259 | * @return 0 if OK (found or not found), other -ve on error | |
260 | */ | |
261 | int uclass_first_device(enum uclass_id id, struct udevice **devp); | |
262 | ||
263 | /** | |
264 | * uclass_first_device_err() - Get the first device in a uclass | |
265 | * | |
266 | * The device returned is probed if necessary, and ready for use | |
267 | * | |
268 | * @id: Uclass ID to look up | |
269 | * @devp: Returns pointer to the first device in that uclass, or NULL if none | |
270 | * @return 0 if found, -ENODEV if not found, other -ve on error | |
271 | */ | |
272 | int uclass_first_device_err(enum uclass_id id, struct udevice **devp); | |
273 | ||
274 | /** | |
275 | * uclass_next_device() - Get the next device in a uclass | |
276 | * | |
277 | * The device returned is probed if necessary, and ready for use | |
278 | * | |
279 | * This function is useful to start iterating through a list of devices which | |
280 | * are functioning correctly and can be probed. | |
281 | * | |
282 | * @devp: On entry, pointer to device to lookup. On exit, returns pointer | |
283 | * to the next device in the uclass if no error occurred, or NULL if there is | |
284 | * no next device, or an error occurred with that next device. | |
285 | * @return 0 if OK (found or not found), other -ve on error | |
286 | */ | |
287 | int uclass_next_device(struct udevice **devp); | |
288 | ||
289 | /** | |
290 | * uclass_first_device() - Get the first device in a uclass | |
291 | * | |
292 | * The device returned is probed if necessary, and ready for use | |
293 | * | |
294 | * This function is useful to start iterating through a list of devices which | |
295 | * are functioning correctly and can be probed. | |
296 | * | |
297 | * @id: Uclass ID to look up | |
298 | * @devp: Returns pointer to the first device in that uclass, or NULL if there | |
299 | * is no first device | |
300 | * @return 0 if OK (found or not found), other -ve on error. If an error occurs | |
301 | * it is still possible to move to the next device. | |
302 | */ | |
303 | int uclass_first_device_check(enum uclass_id id, struct udevice **devp); | |
304 | ||
305 | /** | |
306 | * uclass_next_device() - Get the next device in a uclass | |
307 | * | |
308 | * The device returned is probed if necessary, and ready for use | |
309 | * | |
310 | * This function is useful to start iterating through a list of devices which | |
311 | * are functioning correctly and can be probed. | |
312 | * | |
313 | * @devp: On entry, pointer to device to lookup. On exit, returns pointer | |
314 | * to the next device in the uclass if any | |
315 | * @return 0 if OK (found or not found), other -ve on error. If an error occurs | |
316 | * it is still possible to move to the next device. | |
317 | */ | |
318 | int uclass_next_device_check(struct udevice **devp); | |
319 | ||
320 | /** | |
321 | * uclass_resolve_seq() - Resolve a device's sequence number | |
322 | * | |
323 | * On entry dev->seq is -1, and dev->req_seq may be -1 (to allocate a | |
324 | * sequence number automatically, or >= 0 to select a particular number. | |
325 | * If the requested sequence number is in use, then this device will | |
326 | * be allocated another one. | |
327 | * | |
328 | * Note that the device's seq value is not changed by this function. | |
329 | * | |
330 | * @dev: Device for which to allocate sequence number | |
331 | * @return sequence number allocated, or -ve on error | |
332 | */ | |
333 | int uclass_resolve_seq(struct udevice *dev); | |
334 | ||
335 | /** | |
336 | * uclass_foreach_dev() - Helper function to iteration through devices | |
337 | * | |
338 | * This creates a for() loop which works through the available devices in | |
339 | * a uclass in order from start to end. | |
340 | * | |
341 | * @pos: struct udevice * to hold the current device. Set to NULL when there | |
342 | * are no more devices. | |
343 | * @uc: uclass to scan | |
344 | */ | |
345 | #define uclass_foreach_dev(pos, uc) \ | |
346 | list_for_each_entry(pos, &uc->dev_head, uclass_node) | |
347 | ||
348 | /** | |
349 | * uclass_foreach_dev_safe() - Helper function to safely iteration through devs | |
350 | * | |
351 | * This creates a for() loop which works through the available devices in | |
352 | * a uclass in order from start to end. Inside the loop, it is safe to remove | |
353 | * @pos if required. | |
354 | * | |
355 | * @pos: struct udevice * to hold the current device. Set to NULL when there | |
356 | * are no more devices. | |
357 | * @next: struct udevice * to hold the next next | |
358 | * @uc: uclass to scan | |
359 | */ | |
360 | #define uclass_foreach_dev_safe(pos, next, uc) \ | |
361 | list_for_each_entry_safe(pos, next, &uc->dev_head, uclass_node) | |
362 | ||
363 | #endif |