]>
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 | * Marek Vasut <marex@denx.de> | |
7 | * | |
8 | * SPDX-License-Identifier: GPL-2.0+ | |
9 | */ | |
10 | ||
11 | #ifndef _DM_DEVICE_H | |
12 | #define _DM_DEVICE_H | |
13 | ||
14 | #include <dm/uclass-id.h> | |
15 | #include <linker_lists.h> | |
16 | #include <linux/list.h> | |
17 | ||
18 | struct driver_info; | |
19 | ||
20 | /* Driver is active (probed). Cleared when it is removed */ | |
21 | #define DM_FLAG_ACTIVATED (1 << 0) | |
22 | ||
23 | /* DM is responsible for allocating and freeing platdata */ | |
f2bc6fc3 | 24 | #define DM_FLAG_ALLOC_PDATA (1 << 1) |
6494d708 | 25 | |
00606d7e SG |
26 | /* DM should init this device prior to relocation */ |
27 | #define DM_FLAG_PRE_RELOC (1 << 2) | |
28 | ||
cdc133bd SG |
29 | /* DM is responsible for allocating and freeing parent_platdata */ |
30 | #define DM_FLAG_ALLOC_PARENT_PDATA (1 << 3) | |
31 | ||
6494d708 | 32 | /** |
54c5d08a | 33 | * struct udevice - An instance of a driver |
6494d708 SG |
34 | * |
35 | * This holds information about a device, which is a driver bound to a | |
36 | * particular port or peripheral (essentially a driver instance). | |
37 | * | |
38 | * A device will come into existence through a 'bind' call, either due to | |
39 | * a U_BOOT_DEVICE() macro (in which case platdata is non-NULL) or a node | |
40 | * in the device tree (in which case of_offset is >= 0). In the latter case | |
41 | * we translate the device tree information into platdata in a function | |
42 | * implemented by the driver ofdata_to_platdata method (called just before the | |
43 | * probe method if the device has a device tree node. | |
44 | * | |
45 | * All three of platdata, priv and uclass_priv can be allocated by the | |
46 | * driver, or you can use the auto_alloc_size members of struct driver and | |
47 | * struct uclass_driver to have driver model do this automatically. | |
48 | * | |
49 | * @driver: The driver used by this device | |
50 | * @name: Name of device, typically the FDT node name | |
51 | * @platdata: Configuration data for this device | |
cdc133bd | 52 | * @parent_platdata: The parent bus's configuration data for this device |
6494d708 | 53 | * @of_offset: Device tree node offset for this device (- for none) |
2ef249b4 | 54 | * @of_id: Pointer to the udevice_id structure which created the device |
6494d708 SG |
55 | * @parent: Parent of this device, or NULL for the top level device |
56 | * @priv: Private data for this device | |
57 | * @uclass: Pointer to uclass for this device | |
58 | * @uclass_priv: The uclass's private data for this device | |
e59f458d | 59 | * @parent_priv: The parent's private data for this device |
6494d708 SG |
60 | * @uclass_node: Used by uclass to link its devices |
61 | * @child_head: List of children of this device | |
62 | * @sibling_node: Next device in list of all devices | |
63 | * @flags: Flags for this device DM_FLAG_... | |
5a66a8ff | 64 | * @req_seq: Requested sequence number for this device (-1 = any) |
547cea19 SG |
65 | * @seq: Allocated sequence number for this device (-1 = none). This is set up |
66 | * when the device is probed and will be unique within the device's uclass. | |
6494d708 | 67 | */ |
54c5d08a | 68 | struct udevice { |
6494d708 SG |
69 | struct driver *driver; |
70 | const char *name; | |
71 | void *platdata; | |
cdc133bd | 72 | void *parent_platdata; |
6494d708 | 73 | int of_offset; |
2ef249b4 | 74 | const struct udevice_id *of_id; |
54c5d08a | 75 | struct udevice *parent; |
6494d708 SG |
76 | void *priv; |
77 | struct uclass *uclass; | |
78 | void *uclass_priv; | |
e59f458d | 79 | void *parent_priv; |
6494d708 SG |
80 | struct list_head uclass_node; |
81 | struct list_head child_head; | |
82 | struct list_head sibling_node; | |
83 | uint32_t flags; | |
5a66a8ff SG |
84 | int req_seq; |
85 | int seq; | |
6494d708 SG |
86 | }; |
87 | ||
5a66a8ff SG |
88 | /* Maximum sequence number supported */ |
89 | #define DM_MAX_SEQ 999 | |
90 | ||
6494d708 SG |
91 | /* Returns the operations for a device */ |
92 | #define device_get_ops(dev) (dev->driver->ops) | |
93 | ||
94 | /* Returns non-zero if the device is active (probed and not removed) */ | |
95 | #define device_active(dev) ((dev)->flags & DM_FLAG_ACTIVATED) | |
96 | ||
97 | /** | |
ae7f4513 | 98 | * struct udevice_id - Lists the compatible strings supported by a driver |
6494d708 SG |
99 | * @compatible: Compatible string |
100 | * @data: Data for this compatible string | |
101 | */ | |
ae7f4513 | 102 | struct udevice_id { |
6494d708 SG |
103 | const char *compatible; |
104 | ulong data; | |
105 | }; | |
106 | ||
f887cb6d MY |
107 | #ifdef CONFIG_OF_CONTROL |
108 | #define of_match_ptr(_ptr) (_ptr) | |
109 | #else | |
110 | #define of_match_ptr(_ptr) NULL | |
111 | #endif /* CONFIG_OF_CONTROL */ | |
112 | ||
6494d708 SG |
113 | /** |
114 | * struct driver - A driver for a feature or peripheral | |
115 | * | |
116 | * This holds methods for setting up a new device, and also removing it. | |
117 | * The device needs information to set itself up - this is provided either | |
118 | * by platdata or a device tree node (which we find by looking up | |
119 | * matching compatible strings with of_match). | |
120 | * | |
121 | * Drivers all belong to a uclass, representing a class of devices of the | |
122 | * same type. Common elements of the drivers can be implemented in the uclass, | |
123 | * or the uclass can provide a consistent interface to the drivers within | |
124 | * it. | |
125 | * | |
126 | * @name: Device name | |
127 | * @id: Identiies the uclass we belong to | |
128 | * @of_match: List of compatible strings to match, and any identifying data | |
129 | * for each. | |
130 | * @bind: Called to bind a device to its driver | |
131 | * @probe: Called to probe a device, i.e. activate it | |
132 | * @remove: Called to remove a device, i.e. de-activate it | |
133 | * @unbind: Called to unbind a device from its driver | |
134 | * @ofdata_to_platdata: Called before probe to decode device tree data | |
0118ce79 | 135 | * @child_post_bind: Called after a new child has been bound |
a327dee0 SG |
136 | * @child_pre_probe: Called before a child device is probed. The device has |
137 | * memory allocated but it has not yet been probed. | |
138 | * @child_post_remove: Called after a child device is removed. The device | |
139 | * has memory allocated but its device_remove() method has been called. | |
6494d708 SG |
140 | * @priv_auto_alloc_size: If non-zero this is the size of the private data |
141 | * to be allocated in the device's ->priv pointer. If zero, then the driver | |
142 | * is responsible for allocating any data required. | |
143 | * @platdata_auto_alloc_size: If non-zero this is the size of the | |
144 | * platform data to be allocated in the device's ->platdata pointer. | |
145 | * This is typically only useful for device-tree-aware drivers (those with | |
146 | * an of_match), since drivers which use platdata will have the data | |
147 | * provided in the U_BOOT_DEVICE() instantiation. | |
e59f458d SG |
148 | * @per_child_auto_alloc_size: Each device can hold private data owned by |
149 | * its parent. If required this will be automatically allocated if this | |
150 | * value is non-zero. | |
accd4b19 SG |
151 | * TODO(sjg@chromium.org): I'm considering dropping this, and just having |
152 | * device_probe_child() pass it in. So far the use case for allocating it | |
153 | * is SPI, but I found that unsatisfactory. Since it is here I will leave it | |
154 | * until things are clearer. | |
cdc133bd SG |
155 | * @per_child_platdata_auto_alloc_size: A bus likes to store information about |
156 | * its children. If non-zero this is the size of this data, to be allocated | |
157 | * in the child's parent_platdata pointer. | |
0040b944 | 158 | * @ops: Driver-specific operations. This is typically a list of function |
6494d708 SG |
159 | * pointers defined by the driver, to implement driver functions required by |
160 | * the uclass. | |
00606d7e | 161 | * @flags: driver flags - see DM_FLAGS_... |
6494d708 SG |
162 | */ |
163 | struct driver { | |
164 | char *name; | |
165 | enum uclass_id id; | |
ae7f4513 | 166 | const struct udevice_id *of_match; |
54c5d08a HS |
167 | int (*bind)(struct udevice *dev); |
168 | int (*probe)(struct udevice *dev); | |
169 | int (*remove)(struct udevice *dev); | |
170 | int (*unbind)(struct udevice *dev); | |
171 | int (*ofdata_to_platdata)(struct udevice *dev); | |
0118ce79 | 172 | int (*child_post_bind)(struct udevice *dev); |
a327dee0 SG |
173 | int (*child_pre_probe)(struct udevice *dev); |
174 | int (*child_post_remove)(struct udevice *dev); | |
6494d708 SG |
175 | int priv_auto_alloc_size; |
176 | int platdata_auto_alloc_size; | |
e59f458d | 177 | int per_child_auto_alloc_size; |
cdc133bd | 178 | int per_child_platdata_auto_alloc_size; |
6494d708 | 179 | const void *ops; /* driver-specific operations */ |
00606d7e | 180 | uint32_t flags; |
6494d708 SG |
181 | }; |
182 | ||
183 | /* Declare a new U-Boot driver */ | |
184 | #define U_BOOT_DRIVER(__name) \ | |
185 | ll_entry_declare(struct driver, __name, driver) | |
186 | ||
187 | /** | |
188 | * dev_get_platdata() - Get the platform data for a device | |
189 | * | |
190 | * This checks that dev is not NULL, but no other checks for now | |
191 | * | |
192 | * @dev Device to check | |
193 | * @return platform data, or NULL if none | |
194 | */ | |
54c5d08a | 195 | void *dev_get_platdata(struct udevice *dev); |
6494d708 | 196 | |
cdc133bd SG |
197 | /** |
198 | * dev_get_parent_platdata() - Get the parent platform data for a device | |
199 | * | |
200 | * This checks that dev is not NULL, but no other checks for now | |
201 | * | |
202 | * @dev Device to check | |
203 | * @return parent's platform data, or NULL if none | |
204 | */ | |
205 | void *dev_get_parent_platdata(struct udevice *dev); | |
206 | ||
e59f458d SG |
207 | /** |
208 | * dev_get_parentdata() - Get the parent data for a device | |
209 | * | |
210 | * The parent data is data stored in the device but owned by the parent. | |
211 | * For example, a USB device may have parent data which contains information | |
212 | * about how to talk to the device over USB. | |
213 | * | |
214 | * This checks that dev is not NULL, but no other checks for now | |
215 | * | |
216 | * @dev Device to check | |
217 | * @return parent data, or NULL if none | |
218 | */ | |
219 | void *dev_get_parentdata(struct udevice *dev); | |
220 | ||
6494d708 SG |
221 | /** |
222 | * dev_get_priv() - Get the private data for a device | |
223 | * | |
224 | * This checks that dev is not NULL, but no other checks for now | |
225 | * | |
226 | * @dev Device to check | |
227 | * @return private data, or NULL if none | |
228 | */ | |
54c5d08a | 229 | void *dev_get_priv(struct udevice *dev); |
6494d708 | 230 | |
479728cb SG |
231 | /** |
232 | * struct dev_get_parent() - Get the parent of a device | |
233 | * | |
234 | * @child: Child to check | |
235 | * @return parent of child, or NULL if this is the root device | |
236 | */ | |
237 | struct udevice *dev_get_parent(struct udevice *child); | |
238 | ||
2ef249b4 SG |
239 | /** |
240 | * dev_get_of_data() - get the device tree data used to bind a device | |
241 | * | |
242 | * When a device is bound using a device tree node, it matches a | |
243 | * particular compatible string as in struct udevice_id. This function | |
244 | * returns the associated data value for that compatible string | |
245 | */ | |
246 | ulong dev_get_of_data(struct udevice *dev); | |
247 | ||
997c87bb SG |
248 | /** |
249 | * device_get_child() - Get the child of a device by index | |
250 | * | |
251 | * Returns the numbered child, 0 being the first. This does not use | |
252 | * sequence numbers, only the natural order. | |
253 | * | |
254 | * @dev: Parent device to check | |
255 | * @index: Child index | |
256 | * @devp: Returns pointer to device | |
257 | */ | |
258 | int device_get_child(struct udevice *parent, int index, struct udevice **devp); | |
259 | ||
5a66a8ff SG |
260 | /** |
261 | * device_find_child_by_seq() - Find a child device based on a sequence | |
262 | * | |
263 | * This searches for a device with the given seq or req_seq. | |
264 | * | |
265 | * For seq, if an active device has this sequence it will be returned. | |
266 | * If there is no such device then this will return -ENODEV. | |
267 | * | |
268 | * For req_seq, if a device (whether activated or not) has this req_seq | |
269 | * value, that device will be returned. This is a strong indication that | |
270 | * the device will receive that sequence when activated. | |
271 | * | |
272 | * @parent: Parent device | |
273 | * @seq_or_req_seq: Sequence number to find (0=first) | |
274 | * @find_req_seq: true to find req_seq, false to find seq | |
275 | * @devp: Returns pointer to device (there is only one per for each seq). | |
276 | * Set to NULL if none is found | |
277 | * @return 0 if OK, -ve on error | |
278 | */ | |
279 | int device_find_child_by_seq(struct udevice *parent, int seq_or_req_seq, | |
280 | bool find_req_seq, struct udevice **devp); | |
281 | ||
997c87bb SG |
282 | /** |
283 | * device_get_child_by_seq() - Get a child device based on a sequence | |
284 | * | |
285 | * If an active device has this sequence it will be returned. If there is no | |
286 | * such device then this will check for a device that is requesting this | |
287 | * sequence. | |
288 | * | |
289 | * The device is probed to activate it ready for use. | |
290 | * | |
291 | * @parent: Parent device | |
292 | * @seq: Sequence number to find (0=first) | |
293 | * @devp: Returns pointer to device (there is only one per for each seq) | |
294 | * Set to NULL if none is found | |
295 | * @return 0 if OK, -ve on error | |
296 | */ | |
297 | int device_get_child_by_seq(struct udevice *parent, int seq, | |
298 | struct udevice **devp); | |
299 | ||
300 | /** | |
301 | * device_find_child_by_of_offset() - Find a child device based on FDT offset | |
302 | * | |
303 | * Locates a child device by its device tree offset. | |
304 | * | |
305 | * @parent: Parent device | |
306 | * @of_offset: Device tree offset to find | |
307 | * @devp: Returns pointer to device if found, otherwise this is set to NULL | |
308 | * @return 0 if OK, -ve on error | |
309 | */ | |
310 | int device_find_child_by_of_offset(struct udevice *parent, int of_offset, | |
311 | struct udevice **devp); | |
312 | ||
313 | /** | |
314 | * device_get_child_by_of_offset() - Get a child device based on FDT offset | |
315 | * | |
316 | * Locates a child device by its device tree offset. | |
317 | * | |
318 | * The device is probed to activate it ready for use. | |
319 | * | |
320 | * @parent: Parent device | |
321 | * @of_offset: Device tree offset to find | |
322 | * @devp: Returns pointer to device if found, otherwise this is set to NULL | |
323 | * @return 0 if OK, -ve on error | |
324 | */ | |
325 | int device_get_child_by_of_offset(struct udevice *parent, int seq, | |
326 | struct udevice **devp); | |
327 | ||
a8981d4f SG |
328 | /** |
329 | * device_find_first_child() - Find the first child of a device | |
330 | * | |
331 | * @parent: Parent device to search | |
332 | * @devp: Returns first child device, or NULL if none | |
333 | * @return 0 | |
334 | */ | |
335 | int device_find_first_child(struct udevice *parent, struct udevice **devp); | |
336 | ||
337 | /** | |
338 | * device_find_first_child() - Find the first child of a device | |
339 | * | |
340 | * @devp: Pointer to previous child device on entry. Returns pointer to next | |
341 | * child device, or NULL if none | |
342 | * @return 0 | |
343 | */ | |
344 | int device_find_next_child(struct udevice **devp); | |
345 | ||
6494d708 | 346 | #endif |