xref: /openbmc/u-boot/include/dm/uclass.h (revision 430c166b)
1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3  * Copyright (c) 2013 Google, Inc
4  *
5  * (C) Copyright 2012
6  * Pavel Herrmann <morpheus.ibis@gmail.com>
7  */
8 
9 #ifndef _DM_UCLASS_H
10 #define _DM_UCLASS_H
11 
12 #include <dm/ofnode.h>
13 #include <dm/uclass-id.h>
14 #include <linker_lists.h>
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'
30  * @dev_head: List of devices in this uclass (devices are attached to their
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 
41 struct driver;
42 struct udevice;
43 
44 /* Members of this uclass sequence themselves with aliases */
45 #define DM_UC_FLAG_SEQ_ALIAS			(1 << 0)
46 
47 /* Same as DM_FLAG_ALLOC_PRIV_DMA */
48 #define DM_UC_FLAG_ALLOC_PRIV_DMA		(1 << 5)
49 
50 /**
51  * struct uclass_driver - Driver for the uclass
52  *
53  * A uclass_driver provides a consistent interface to a set of related
54  * drivers.
55  *
56  * @name: Name of uclass driver
57  * @id: ID number of this uclass
58  * @post_bind: Called after a new device is bound to this uclass
59  * @pre_unbind: Called before a device is unbound from this uclass
60  * @pre_probe: Called before a new device is probed
61  * @post_probe: Called after a new device is probed
62  * @pre_remove: Called before a device is removed
63  * @child_post_bind: Called after a child is bound to a device in this uclass
64  * @child_pre_probe: Called before a child in this uclass is probed
65  * @child_post_probe: Called after a child in this uclass is probed
66  * @init: Called to set up the uclass
67  * @destroy: Called to destroy the uclass
68  * @priv_auto_alloc_size: If non-zero this is the size of the private data
69  * to be allocated in the uclass's ->priv pointer. If zero, then the uclass
70  * driver is responsible for allocating any data required.
71  * @per_device_auto_alloc_size: Each device can hold private data owned
72  * by the uclass. If required this will be automatically allocated if this
73  * value is non-zero.
74  * @per_device_platdata_auto_alloc_size: Each device can hold platform data
75  * owned by the uclass as 'dev->uclass_platdata'. If the value is non-zero,
76  * then this will be automatically allocated.
77  * @per_child_auto_alloc_size: Each child device (of a parent in this
78  * uclass) can hold parent data for the device/uclass. This value is only
79  * used as a fallback if this member is 0 in the driver.
80  * @per_child_platdata_auto_alloc_size: A bus likes to store information about
81  * its children. If non-zero this is the size of this data, to be allocated
82  * in the child device's parent_platdata pointer. This value is only used as
83  * a fallback if this member is 0 in the driver.
84  * @ops: Uclass operations, providing the consistent interface to devices
85  * within the uclass.
86  * @flags: Flags for this uclass (DM_UC_...)
87  */
88 struct uclass_driver {
89 	const char *name;
90 	enum uclass_id id;
91 	int (*post_bind)(struct udevice *dev);
92 	int (*pre_unbind)(struct udevice *dev);
93 	int (*pre_probe)(struct udevice *dev);
94 	int (*post_probe)(struct udevice *dev);
95 	int (*pre_remove)(struct udevice *dev);
96 	int (*child_post_bind)(struct udevice *dev);
97 	int (*child_pre_probe)(struct udevice *dev);
98 	int (*child_post_probe)(struct udevice *dev);
99 	int (*init)(struct uclass *class);
100 	int (*destroy)(struct uclass *class);
101 	int priv_auto_alloc_size;
102 	int per_device_auto_alloc_size;
103 	int per_device_platdata_auto_alloc_size;
104 	int per_child_auto_alloc_size;
105 	int per_child_platdata_auto_alloc_size;
106 	const void *ops;
107 	uint32_t flags;
108 };
109 
110 /* Declare a new uclass_driver */
111 #define UCLASS_DRIVER(__name)						\
112 	ll_entry_declare(struct uclass_driver, __name, uclass)
113 
114 /**
115  * uclass_get() - Get a uclass based on an ID, creating it if needed
116  *
117  * Every uclass is identified by an ID, a number from 0 to n-1 where n is
118  * the number of uclasses. This function allows looking up a uclass by its
119  * ID.
120  *
121  * @key: ID to look up
122  * @ucp: Returns pointer to uclass (there is only one per ID)
123  * @return 0 if OK, -ve on error
124  */
125 int uclass_get(enum uclass_id key, struct uclass **ucp);
126 
127 /**
128  * uclass_get_name() - Get the name of a uclass driver
129  *
130  * @id: ID to look up
131  * @returns the name of the uclass driver for that ID, or NULL if none
132  */
133 const char *uclass_get_name(enum uclass_id id);
134 
135 /**
136  * uclass_get_by_name() - Look up a uclass by its driver name
137  *
138  * @name: Name to look up
139  * @returns the associated uclass ID, or UCLASS_INVALID if not found
140  */
141 enum uclass_id uclass_get_by_name(const char *name);
142 
143 /**
144  * uclass_get_device() - Get a uclass device based on an ID and index
145  *
146  * The device is probed to activate it ready for use.
147  *
148  * @id: ID to look up
149  * @index: Device number within that uclass (0=first)
150  * @devp: Returns pointer to device (there is only one per for each ID)
151  * @return 0 if OK, -ve on error
152  */
153 int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
154 
155 /**
156  * uclass_get_device_by_name() - Get a uclass device by its name
157  *
158  * This searches the devices in the uclass for one with the exactly given name.
159  *
160  * The device is probed to activate it ready for use.
161  *
162  * @id: ID to look up
163  * @name: name of a device to get
164  * @devp: Returns pointer to device (the first one with the name)
165  * @return 0 if OK, -ve on error
166  */
167 int uclass_get_device_by_name(enum uclass_id id, const char *name,
168 			      struct udevice **devp);
169 
170 /**
171  * uclass_get_device_by_seq() - Get a uclass device based on an ID and sequence
172  *
173  * If an active device has this sequence it will be returned. If there is no
174  * such device then this will check for a device that is requesting this
175  * sequence.
176  *
177  * The device is probed to activate it ready for use.
178  *
179  * @id: ID to look up
180  * @seq: Sequence number to find (0=first)
181  * @devp: Returns pointer to device (there is only one for each seq)
182  * @return 0 if OK, -ve on error
183  */
184 int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp);
185 
186 /**
187  * uclass_get_device_by_of_offset() - Get a uclass device by device tree node
188  *
189  * This searches the devices in the uclass for one attached to the given
190  * device tree node.
191  *
192  * The device is probed to activate it ready for use.
193  *
194  * @id: ID to look up
195  * @node: Device tree offset to search for (if -ve then -ENODEV is returned)
196  * @devp: Returns pointer to device (there is only one for each node)
197  * @return 0 if OK, -ve on error
198  */
199 int uclass_get_device_by_of_offset(enum uclass_id id, int node,
200 				   struct udevice **devp);
201 
202 /**
203  * uclass_get_device_by_ofnode() - Get a uclass device by device tree node
204  *
205  * This searches the devices in the uclass for one attached to the given
206  * device tree node.
207  *
208  * The device is probed to activate it ready for use.
209  *
210  * @id: ID to look up
211  * @np: Device tree node to search for (if NULL then -ENODEV is returned)
212  * @devp: Returns pointer to device (there is only one for each node)
213  * @return 0 if OK, -ve on error
214  */
215 int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node,
216 				struct udevice **devp);
217 
218 /**
219  * uclass_get_device_by_phandle_id() - Get a uclass device by phandle id
220  *
221  * This searches the devices in the uclass for one with the given phandle id.
222  *
223  * The device is probed to activate it ready for use.
224  *
225  * @id: uclass ID to look up
226  * @phandle_id: the phandle id to look up
227  * @devp: Returns pointer to device (there is only one for each node)
228  * @return 0 if OK, -ENODEV if there is no device match the phandle, other
229  *	-ve on error
230  */
231 int uclass_get_device_by_phandle_id(enum uclass_id id, uint phandle_id,
232 				    struct udevice **devp);
233 
234 /**
235  * uclass_get_device_by_phandle() - Get a uclass device by phandle
236  *
237  * This searches the devices in the uclass for one with the given phandle.
238  *
239  * The device is probed to activate it ready for use.
240  *
241  * @id: uclass ID to look up
242  * @parent: Parent device containing the phandle pointer
243  * @name: Name of property in the parent device node
244  * @devp: Returns pointer to device (there is only one for each node)
245  * @return 0 if OK, -ENOENT if there is no @name present in the node, other
246  *	-ve on error
247  */
248 int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent,
249 				 const char *name, struct udevice **devp);
250 
251 /**
252  * uclass_get_device_by_driver() - Get a uclass device for a driver
253  *
254  * This searches the devices in the uclass for one that uses the given
255  * driver. Use DM_GET_DRIVER(name) for the @drv argument, where 'name' is
256  * the driver name - as used in U_BOOT_DRIVER(name).
257  *
258  * The device is probed to activate it ready for use.
259  *
260  * @id: ID to look up
261  * @drv: Driver to look for
262  * @devp: Returns pointer to the first device with that driver
263  * @return 0 if OK, -ve on error
264  */
265 int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv,
266 				struct udevice **devp);
267 
268 /**
269  * uclass_first_device() - Get the first device in a uclass
270  *
271  * The device returned is probed if necessary, and ready for use
272  *
273  * This function is useful to start iterating through a list of devices which
274  * are functioning correctly and can be probed.
275  *
276  * @id: Uclass ID to look up
277  * @devp: Returns pointer to the first device in that uclass if no error
278  * occurred, or NULL if there is no first device, or an error occurred with
279  * that device.
280  * @return 0 if OK (found or not found), other -ve on error
281  */
282 int uclass_first_device(enum uclass_id id, struct udevice **devp);
283 
284 /**
285  * uclass_first_device_err() - Get the first device in a uclass
286  *
287  * The device returned is probed if necessary, and ready for use
288  *
289  * @id: Uclass ID to look up
290  * @devp: Returns pointer to the first device in that uclass, or NULL if none
291  * @return 0 if found, -ENODEV if not found, other -ve on error
292  */
293 int uclass_first_device_err(enum uclass_id id, struct udevice **devp);
294 
295 /**
296  * uclass_next_device() - Get the next device in a uclass
297  *
298  * The device returned is probed if necessary, and ready for use
299  *
300  * This function is useful to start iterating through a list of devices which
301  * are functioning correctly and can be probed.
302  *
303  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
304  * to the next device in the uclass if no error occurred, or NULL if there is
305  * no next device, or an error occurred with that next device.
306  * @return 0 if OK (found or not found), other -ve on error
307  */
308 int uclass_next_device(struct udevice **devp);
309 
310 /**
311  * uclass_next_device_err() - Get the next device in a uclass
312  *
313  * The device returned is probed if necessary, and ready for use
314  *
315  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
316  * to the next device in the uclass if no error occurred, or -ENODEV if
317  * there is no next device.
318  * @return 0 if found, -ENODEV if not found, other -ve on error
319  */
320 int uclass_next_device_err(struct udevice **devp);
321 
322 /**
323  * uclass_first_device_check() - Get the first device in a uclass
324  *
325  * The device returned is probed if necessary, and ready for use
326  *
327  * This function is useful to start iterating through a list of devices which
328  * are functioning correctly and can be probed.
329  *
330  * @id: Uclass ID to look up
331  * @devp: Returns pointer to the first device in that uclass, or NULL if there
332  * is no first device
333  * @return 0 if OK (found or not found), other -ve on error. If an error occurs
334  * it is still possible to move to the next device.
335  */
336 int uclass_first_device_check(enum uclass_id id, struct udevice **devp);
337 
338 /**
339  * uclass_next_device_check() - Get the next device in a uclass
340  *
341  * The device returned is probed if necessary, and ready for use
342  *
343  * This function is useful to start iterating through a list of devices which
344  * are functioning correctly and can be probed.
345  *
346  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
347  * to the next device in the uclass if any
348  * @return 0 if OK (found or not found), other -ve on error. If an error occurs
349  * it is still possible to move to the next device.
350  */
351 int uclass_next_device_check(struct udevice **devp);
352 
353 /**
354  * uclass_resolve_seq() - Resolve a device's sequence number
355  *
356  * On entry dev->seq is -1, and dev->req_seq may be -1 (to allocate a
357  * sequence number automatically, or >= 0 to select a particular number.
358  * If the requested sequence number is in use, then this device will
359  * be allocated another one.
360  *
361  * Note that the device's seq value is not changed by this function.
362  *
363  * @dev: Device for which to allocate sequence number
364  * @return sequence number allocated, or -ve on error
365  */
366 int uclass_resolve_seq(struct udevice *dev);
367 
368 /**
369  * uclass_foreach_dev() - Helper function to iteration through devices
370  *
371  * This creates a for() loop which works through the available devices in
372  * a uclass in order from start to end.
373  *
374  * @pos: struct udevice * to hold the current device. Set to NULL when there
375  * are no more devices.
376  * @uc: uclass to scan
377  */
378 #define uclass_foreach_dev(pos, uc)	\
379 	list_for_each_entry(pos, &uc->dev_head, uclass_node)
380 
381 /**
382  * uclass_foreach_dev_safe() - Helper function to safely iteration through devs
383  *
384  * This creates a for() loop which works through the available devices in
385  * a uclass in order from start to end. Inside the loop, it is safe to remove
386  * @pos if required.
387  *
388  * @pos: struct udevice * to hold the current device. Set to NULL when there
389  * are no more devices.
390  * @next: struct udevice * to hold the next next
391  * @uc: uclass to scan
392  */
393 #define uclass_foreach_dev_safe(pos, next, uc)	\
394 	list_for_each_entry_safe(pos, next, &uc->dev_head, uclass_node)
395 
396 /**
397  * uclass_foreach_dev_probe() - Helper function to iteration through devices
398  * of given uclass
399  *
400  * This creates a for() loop which works through the available devices in
401  * a uclass in order from start to end. Devices are probed if necessary,
402  * and ready for use.
403  *
404  * @id: Uclass ID
405  * @dev: struct udevice * to hold the current device. Set to NULL when there
406  * are no more devices.
407  */
408 #define uclass_foreach_dev_probe(id, dev)	\
409 	for (int _ret = uclass_first_device_err(id, &dev); !_ret && dev; \
410 	     _ret = uclass_next_device_err(&dev))
411 
412 #endif
413