include/dm/uclass.h

7  * SPDX-License-Identifier:	GPL-2.0+
14 #include <dm/uclass-id.h>
19  * struct uclass - a U-Boot drive class, collecting together similar drivers
25  * There may be drivers for on-chip SoC GPIO banks, I2C GPIO expanders and
52  * struct uclass_driver - Driver for the uclass
58  * @id: ID number of this uclass
59  * @post_bind: Called after a new device is bound to this uclass
60  * @pre_unbind: Called before a device is unbound from this uclass
61  * @pre_probe: Called before a new device is probed
62  * @post_probe: Called after a new device is probed
63  * @pre_remove: Called before a device is removed
64  * @child_post_bind: Called after a child is bound to a device in this uclass
67  * @priv_auto_alloc_size: If non-zero this is the size of the private data
68  * to be allocated in the uclass's ->priv pointer. If zero, then the uclass
70  * @per_device_auto_alloc_size: Each device can hold private data owned
72  * value is non-zero.
73  * @per_device_platdata_auto_alloc_size: Each device can hold platform data
74  * owned by the uclass as 'dev->uclass_platdata'. If the value is non-zero,
76  * @per_child_auto_alloc_size: Each child device (of a parent in this
77  * uclass) can hold parent data for the device/uclass. This value is only
80  * its children. If non-zero this is the size of this data, to be allocated
81  * in the child device's parent_platdata pointer. This value is only used as
89 	enum uclass_id id;  member
113  * uclass_get() - Get a uclass based on an ID, creating it if needed
115  * Every uclass is identified by an ID, a number from 0 to n-1 where n is
117  * ID.
119  * @key: ID to look up
120  * @ucp: Returns pointer to uclass (there is only one per ID)
121  * @return 0 if OK, -ve on error
126  * uclass_get_name() - Get the name of a uclass driver
128  * @id: ID to look up
129  * @returns the name of the uclass driver for that ID, or NULL if none
131 const char *uclass_get_name(enum uclass_id id);
134  * uclass_get_by_name() - Look up a uclass by its driver name
137  * @returns the associated uclass ID, or UCLASS_INVALID if not found
142  * uclass_get_device() - Get a uclass device based on an ID and index
144  * The device is probed to activate it ready for use.
146  * @id: ID to look up
147  * @index: Device number within that uclass (0=first)
148  * @devp: Returns pointer to device (there is only one per for each ID)
149  * @return 0 if OK, -ve on error
151 int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
154  * uclass_get_device_by_name() - Get a uclass device by its name
158  * The device is probed to activate it ready for use.
160  * @id: ID to look up
161  * @name: name of a device to get
162  * @devp: Returns pointer to device (the first one with the name)
163  * @return 0 if OK, -ve on error
165 int uclass_get_device_by_name(enum uclass_id id, const char *name,
169  * uclass_get_device_by_seq() - Get a uclass device based on an ID and sequence
171  * If an active device has this sequence it will be returned. If there is no
172  * such device then this will check for a device that is requesting this
175  * The device is probed to activate it ready for use.
177  * @id: ID to look up
179  * @devp: Returns pointer to device (there is only one for each seq)
180  * @return 0 if OK, -ve on error
182 int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp);
185  * uclass_get_device_by_of_offset() - Get a uclass device by device tree node
188  * device tree node.
190  * The device is probed to activate it ready for use.
192  * @id: ID to look up
193  * @node: Device tree offset to search for (if -ve then -ENODEV is returned)
194  * @devp: Returns pointer to device (there is only one for each node)
195  * @return 0 if OK, -ve on error
197 int uclass_get_device_by_of_offset(enum uclass_id id, int node,
201  * uclass_get_device_by_ofnode() - Get a uclass device by device tree node
204  * device tree node.
206  * The device is probed to activate it ready for use.
208  * @id: ID to look up
209  * @np: Device tree node to search for (if NULL then -ENODEV is returned)
210  * @devp: Returns pointer to device (there is only one for each node)
211  * @return 0 if OK, -ve on error
213 int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node,
217  * uclass_get_device_by_phandle_id() - Get a uclass device by phandle id
219  * This searches the devices in the uclass for one with the given phandle id.
221  * The device is probed to activate it ready for use.
223  * @id: uclass ID to look up
224  * @phandle_id: the phandle id to look up
225  * @devp: Returns pointer to device (there is only one for each node)
226  * @return 0 if OK, -ENODEV if there is no device match the phandle, other
227  *	-ve on error
229 int uclass_get_device_by_phandle_id(enum uclass_id id, uint phandle_id,
233  * uclass_get_device_by_phandle() - Get a uclass device by phandle
237  * The device is probed to activate it ready for use.
239  * @id: uclass ID to look up
240  * @parent: Parent device containing the phandle pointer
241  * @name: Name of property in the parent device node
242  * @devp: Returns pointer to device (there is only one for each node)
243  * @return 0 if OK, -ENOENT if there is no @name present in the node, other
244  *	-ve on error
246 int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent,
250  * uclass_get_device_by_driver() - Get a uclass device for a driver
254  * the driver name - as used in U_BOOT_DRIVER(name).
256  * The device is probed to activate it ready for use.
258  * @id: ID to look up
260  * @devp: Returns pointer to the first device with that driver
261  * @return 0 if OK, -ve on error
263 int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv,
267  * uclass_first_device() - Get the first device in a uclass
269  * The device returned is probed if necessary, and ready for use
274  * @id: Uclass ID to look up
275  * @devp: Returns pointer to the first device in that uclass if no error
276  * occurred, or NULL if there is no first device, or an error occurred with
277  * that device.
278  * @return 0 if OK (found or not found), other -ve on error
280 int uclass_first_device(enum uclass_id id, struct udevice **devp);
283  * uclass_first_device_err() - Get the first device in a uclass
285  * The device returned is probed if necessary, and ready for use
287  * @id: Uclass ID to look up
288  * @devp: Returns pointer to the first device in that uclass, or NULL if none
289  * @return 0 if found, -ENODEV if not found, other -ve on error
291 int uclass_first_device_err(enum uclass_id id, struct udevice **devp);
294  * uclass_next_device() - Get the next device in a uclass
296  * The device returned is probed if necessary, and ready for use
301  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
302  * to the next device in the uclass if no error occurred, or NULL if there is
303  * no next device, or an error occurred with that next device.
304  * @return 0 if OK (found or not found), other -ve on error
309  * uclass_first_device() - Get the first device in a uclass
311  * The device returned is probed if necessary, and ready for use
316  * @id: Uclass ID to look up
317  * @devp: Returns pointer to the first device in that uclass, or NULL if there
318  * is no first device
319  * @return 0 if OK (found or not found), other -ve on error. If an error occurs
320  * it is still possible to move to the next device.
322 int uclass_first_device_check(enum uclass_id id, struct udevice **devp);
325  * uclass_next_device() - Get the next device in a uclass
327  * The device returned is probed if necessary, and ready for use
332  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
333  * to the next device in the uclass if any
334  * @return 0 if OK (found or not found), other -ve on error. If an error occurs
335  * it is still possible to move to the next device.
340  * uclass_resolve_seq() - Resolve a device's sequence number
342  * On entry dev->seq is -1, and dev->req_seq may be -1 (to allocate a
344  * If the requested sequence number is in use, then this device will
347  * Note that the device's seq value is not changed by this function.
349  * @dev: Device for which to allocate sequence number
350  * @return sequence number allocated, or -ve on error
355  * uclass_foreach_dev() - Helper function to iteration through devices
360  * @pos: struct udevice * to hold the current device. Set to NULL when there
365 	list_for_each_entry(pos, &uc->dev_head, uclass_node)
368  * uclass_foreach_dev_safe() - Helper function to safely iteration through devs
374  * @pos: struct udevice * to hold the current device. Set to NULL when there
380 	list_for_each_entry_safe(pos, next, &uc->dev_head, uclass_node)