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