blob: 1138a09149f4b8c1222e5c03eff1a786e9537c44 [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001/* SPDX-License-Identifier: GPL-2.0+ */
Simon Glass6494d702014-02-26 15:59:18 -07002/*
3 * Copyright (c) 2013 Google, Inc
4 *
5 * (C) Copyright 2012
6 * Pavel Herrmann <morpheus.ibis@gmail.com>
7 * Marek Vasut <marex@denx.de>
Simon Glass6494d702014-02-26 15:59:18 -07008 */
9
10#ifndef _DM_DEVICE_H
11#define _DM_DEVICE_H
12
Simon Glass4984de22017-05-17 17:18:10 -060013#include <dm/ofnode.h>
Simon Glass6494d702014-02-26 15:59:18 -070014#include <dm/uclass-id.h>
Peng Fanc9cac3f2015-02-10 14:46:32 +080015#include <fdtdec.h>
Simon Glass6494d702014-02-26 15:59:18 -070016#include <linker_lists.h>
Masahiro Yamada2b07f682015-07-25 21:52:36 +090017#include <linux/compat.h>
18#include <linux/kernel.h>
Simon Glass6494d702014-02-26 15:59:18 -070019#include <linux/list.h>
Masahiro Yamadac898cba2017-09-26 11:58:29 +090020#include <linux/printk.h>
Simon Glass6494d702014-02-26 15:59:18 -070021
22struct driver_info;
23
24/* Driver is active (probed). Cleared when it is removed */
Simon Glassfb04c9d2015-09-28 23:32:03 -060025#define DM_FLAG_ACTIVATED (1 << 0)
Simon Glass6494d702014-02-26 15:59:18 -070026
27/* DM is responsible for allocating and freeing platdata */
Simon Glassfb04c9d2015-09-28 23:32:03 -060028#define DM_FLAG_ALLOC_PDATA (1 << 1)
Simon Glass6494d702014-02-26 15:59:18 -070029
Simon Glass00606d72014-07-23 06:55:03 -060030/* DM should init this device prior to relocation */
Simon Glassfb04c9d2015-09-28 23:32:03 -060031#define DM_FLAG_PRE_RELOC (1 << 2)
Simon Glass00606d72014-07-23 06:55:03 -060032
Simon Glasscdc133b2015-01-25 08:27:01 -070033/* DM is responsible for allocating and freeing parent_platdata */
34#define DM_FLAG_ALLOC_PARENT_PDATA (1 << 3)
35
Przemyslaw Marczak5eaed882015-04-15 13:07:18 +020036/* DM is responsible for allocating and freeing uclass_platdata */
37#define DM_FLAG_ALLOC_UCLASS_PDATA (1 << 4)
38
Simon Glass2c03c462015-03-25 12:21:53 -060039/* Allocate driver private data on a DMA boundary */
Simon Glassfb04c9d2015-09-28 23:32:03 -060040#define DM_FLAG_ALLOC_PRIV_DMA (1 << 5)
Simon Glass2c03c462015-03-25 12:21:53 -060041
Masahiro Yamadaaed1a4d2015-07-25 21:52:34 +090042/* Device is bound */
Simon Glassfb04c9d2015-09-28 23:32:03 -060043#define DM_FLAG_BOUND (1 << 6)
Masahiro Yamadaaed1a4d2015-07-25 21:52:34 +090044
Simon Glassa2040fa2016-05-01 13:52:23 -060045/* Device name is allocated and should be freed on unbind() */
Simon Glassfd1c2d92016-07-04 11:58:15 -060046#define DM_FLAG_NAME_ALLOCED (1 << 7)
Simon Glassa2040fa2016-05-01 13:52:23 -060047
Simon Glass04e19ff2019-12-29 21:19:19 -070048/* Device has platform data provided by of-platdata */
Simon Glass9fa28192016-07-04 11:58:18 -060049#define DM_FLAG_OF_PLATDATA (1 << 8)
50
Stefan Roese706865a2017-03-20 12:51:48 +010051/*
52 * Call driver remove function to stop currently active DMA transfers or
53 * give DMA buffers back to the HW / controller. This may be needed for
54 * some drivers to do some final stage cleanup before the OS is called
55 * (U-Boot exit)
56 */
57#define DM_FLAG_ACTIVE_DMA (1 << 9)
58
59/*
Stefan Roese426f99f2017-04-24 09:48:02 +020060 * Call driver remove function to do some final configuration, before
61 * U-Boot exits and the OS is started
62 */
63#define DM_FLAG_OS_PREPARE (1 << 10)
64
Lokesh Vutlaaf94ad42019-09-27 13:48:12 +053065/* DM does not enable/disable the power domains corresponding to this device */
66#define DM_FLAG_DEFAULT_PD_CTRL_OFF (1 << 11)
67
Simon Glass153851d2019-12-29 21:19:21 -070068/* Driver platdata has been read. Cleared when the device is removed */
69#define DM_FLAG_PLATDATA_VALID (1 << 12)
70
Stefan Roese426f99f2017-04-24 09:48:02 +020071/*
Stefan Roese706865a2017-03-20 12:51:48 +010072 * One or multiple of these flags are passed to device_remove() so that
73 * a selective device removal as specified by the remove-stage and the
74 * driver flags can be done.
75 */
76enum {
77 /* Normal remove, remove all devices */
78 DM_REMOVE_NORMAL = 1 << 0,
79
80 /* Remove devices with active DMA */
81 DM_REMOVE_ACTIVE_DMA = DM_FLAG_ACTIVE_DMA,
82
Stefan Roese426f99f2017-04-24 09:48:02 +020083 /* Remove devices which need some final OS preparation steps */
84 DM_REMOVE_OS_PREPARE = DM_FLAG_OS_PREPARE,
85
Stefan Roese706865a2017-03-20 12:51:48 +010086 /* Add more use cases here */
87
88 /* Remove devices with any active flag */
Stefan Roese426f99f2017-04-24 09:48:02 +020089 DM_REMOVE_ACTIVE_ALL = DM_REMOVE_ACTIVE_DMA | DM_REMOVE_OS_PREPARE,
Stefan Roese706865a2017-03-20 12:51:48 +010090};
91
Simon Glass6494d702014-02-26 15:59:18 -070092/**
Heiko Schocher54c5d082014-05-22 12:43:05 +020093 * struct udevice - An instance of a driver
Simon Glass6494d702014-02-26 15:59:18 -070094 *
95 * This holds information about a device, which is a driver bound to a
96 * particular port or peripheral (essentially a driver instance).
97 *
98 * A device will come into existence through a 'bind' call, either due to
99 * a U_BOOT_DEVICE() macro (in which case platdata is non-NULL) or a node
100 * in the device tree (in which case of_offset is >= 0). In the latter case
101 * we translate the device tree information into platdata in a function
102 * implemented by the driver ofdata_to_platdata method (called just before the
103 * probe method if the device has a device tree node.
104 *
105 * All three of platdata, priv and uclass_priv can be allocated by the
106 * driver, or you can use the auto_alloc_size members of struct driver and
107 * struct uclass_driver to have driver model do this automatically.
108 *
109 * @driver: The driver used by this device
110 * @name: Name of device, typically the FDT node name
111 * @platdata: Configuration data for this device
Simon Glasscdc133b2015-01-25 08:27:01 -0700112 * @parent_platdata: The parent bus's configuration data for this device
Przemyslaw Marczak5eaed882015-04-15 13:07:18 +0200113 * @uclass_platdata: The uclass's configuration data for this device
Simon Glass4984de22017-05-17 17:18:10 -0600114 * @node: Reference to device tree node for this device
Simon Glass39de8432015-03-25 12:21:55 -0600115 * @driver_data: Driver data word for the entry that matched this device with
116 * its driver
Simon Glass6494d702014-02-26 15:59:18 -0700117 * @parent: Parent of this device, or NULL for the top level device
118 * @priv: Private data for this device
119 * @uclass: Pointer to uclass for this device
120 * @uclass_priv: The uclass's private data for this device
Simon Glasse59f4582014-07-23 06:55:20 -0600121 * @parent_priv: The parent's private data for this device
Simon Glass6494d702014-02-26 15:59:18 -0700122 * @uclass_node: Used by uclass to link its devices
123 * @child_head: List of children of this device
124 * @sibling_node: Next device in list of all devices
125 * @flags: Flags for this device DM_FLAG_...
Simon Glass5a66a8f2014-07-23 06:55:12 -0600126 * @req_seq: Requested sequence number for this device (-1 = any)
Simon Glass547cea12014-10-13 23:41:51 -0600127 * @seq: Allocated sequence number for this device (-1 = none). This is set up
128 * when the device is probed and will be unique within the device's uclass.
Simon Glass93c7fe42015-09-28 23:32:04 -0600129 * @devres_head: List of memory allocations associated with this device.
130 * When CONFIG_DEVRES is enabled, devm_kmalloc() and friends will
131 * add to this list. Memory so-allocated will be freed
132 * automatically when the device is removed / unbound
Simon Glass6494d702014-02-26 15:59:18 -0700133 */
Heiko Schocher54c5d082014-05-22 12:43:05 +0200134struct udevice {
Simon Glass34792532015-03-25 12:21:54 -0600135 const struct driver *driver;
Simon Glass6494d702014-02-26 15:59:18 -0700136 const char *name;
137 void *platdata;
Simon Glasscdc133b2015-01-25 08:27:01 -0700138 void *parent_platdata;
Przemyslaw Marczak5eaed882015-04-15 13:07:18 +0200139 void *uclass_platdata;
Simon Glass4984de22017-05-17 17:18:10 -0600140 ofnode node;
Simon Glass39de8432015-03-25 12:21:55 -0600141 ulong driver_data;
Heiko Schocher54c5d082014-05-22 12:43:05 +0200142 struct udevice *parent;
Simon Glass6494d702014-02-26 15:59:18 -0700143 void *priv;
144 struct uclass *uclass;
145 void *uclass_priv;
Simon Glasse59f4582014-07-23 06:55:20 -0600146 void *parent_priv;
Simon Glass6494d702014-02-26 15:59:18 -0700147 struct list_head uclass_node;
148 struct list_head child_head;
149 struct list_head sibling_node;
150 uint32_t flags;
Simon Glass5a66a8f2014-07-23 06:55:12 -0600151 int req_seq;
152 int seq;
Masahiro Yamadae2282d72015-07-25 21:52:37 +0900153#ifdef CONFIG_DEVRES
Masahiro Yamada608f26c2015-07-25 21:52:35 +0900154 struct list_head devres_head;
Masahiro Yamadae2282d72015-07-25 21:52:37 +0900155#endif
Simon Glass6494d702014-02-26 15:59:18 -0700156};
157
Simon Glass5a66a8f2014-07-23 06:55:12 -0600158/* Maximum sequence number supported */
159#define DM_MAX_SEQ 999
160
Simon Glass6494d702014-02-26 15:59:18 -0700161/* Returns the operations for a device */
162#define device_get_ops(dev) (dev->driver->ops)
163
164/* Returns non-zero if the device is active (probed and not removed) */
165#define device_active(dev) ((dev)->flags & DM_FLAG_ACTIVATED)
166
Simon Glasse160f7d2017-01-17 16:52:55 -0700167static inline int dev_of_offset(const struct udevice *dev)
168{
Simon Glass4984de22017-05-17 17:18:10 -0600169 return ofnode_to_offset(dev->node);
Simon Glasse160f7d2017-01-17 16:52:55 -0700170}
171
172static inline void dev_set_of_offset(struct udevice *dev, int of_offset)
173{
Simon Glass4984de22017-05-17 17:18:10 -0600174 dev->node = offset_to_ofnode(of_offset);
175}
176
177static inline bool dev_has_of_node(struct udevice *dev)
178{
179 return ofnode_valid(dev->node);
Simon Glasse160f7d2017-01-17 16:52:55 -0700180}
181
Simon Glass6494d702014-02-26 15:59:18 -0700182/**
Simon Glassae7f4512014-06-11 23:29:45 -0600183 * struct udevice_id - Lists the compatible strings supported by a driver
Simon Glass6494d702014-02-26 15:59:18 -0700184 * @compatible: Compatible string
185 * @data: Data for this compatible string
186 */
Simon Glassae7f4512014-06-11 23:29:45 -0600187struct udevice_id {
Simon Glass6494d702014-02-26 15:59:18 -0700188 const char *compatible;
189 ulong data;
190};
191
Masahiro Yamada0f925822015-08-12 07:31:55 +0900192#if CONFIG_IS_ENABLED(OF_CONTROL)
Masahiro Yamadaf887cb62014-10-07 14:51:31 +0900193#define of_match_ptr(_ptr) (_ptr)
194#else
195#define of_match_ptr(_ptr) NULL
Masahiro Yamada0f925822015-08-12 07:31:55 +0900196#endif /* CONFIG_IS_ENABLED(OF_CONTROL) */
Masahiro Yamadaf887cb62014-10-07 14:51:31 +0900197
Simon Glass6494d702014-02-26 15:59:18 -0700198/**
199 * struct driver - A driver for a feature or peripheral
200 *
201 * This holds methods for setting up a new device, and also removing it.
202 * The device needs information to set itself up - this is provided either
203 * by platdata or a device tree node (which we find by looking up
204 * matching compatible strings with of_match).
205 *
206 * Drivers all belong to a uclass, representing a class of devices of the
207 * same type. Common elements of the drivers can be implemented in the uclass,
208 * or the uclass can provide a consistent interface to the drivers within
209 * it.
210 *
211 * @name: Device name
Heinrich Schuchardt80ee4fc2018-02-12 12:38:36 +0100212 * @id: Identifies the uclass we belong to
Simon Glass6494d702014-02-26 15:59:18 -0700213 * @of_match: List of compatible strings to match, and any identifying data
214 * for each.
215 * @bind: Called to bind a device to its driver
216 * @probe: Called to probe a device, i.e. activate it
217 * @remove: Called to remove a device, i.e. de-activate it
218 * @unbind: Called to unbind a device from its driver
219 * @ofdata_to_platdata: Called before probe to decode device tree data
Simon Glass0118ce72015-01-25 08:27:03 -0700220 * @child_post_bind: Called after a new child has been bound
Simon Glassa327dee2014-07-23 06:55:21 -0600221 * @child_pre_probe: Called before a child device is probed. The device has
222 * memory allocated but it has not yet been probed.
223 * @child_post_remove: Called after a child device is removed. The device
224 * has memory allocated but its device_remove() method has been called.
Simon Glass6494d702014-02-26 15:59:18 -0700225 * @priv_auto_alloc_size: If non-zero this is the size of the private data
226 * to be allocated in the device's ->priv pointer. If zero, then the driver
227 * is responsible for allocating any data required.
228 * @platdata_auto_alloc_size: If non-zero this is the size of the
229 * platform data to be allocated in the device's ->platdata pointer.
230 * This is typically only useful for device-tree-aware drivers (those with
231 * an of_match), since drivers which use platdata will have the data
232 * provided in the U_BOOT_DEVICE() instantiation.
Simon Glasse59f4582014-07-23 06:55:20 -0600233 * @per_child_auto_alloc_size: Each device can hold private data owned by
234 * its parent. If required this will be automatically allocated if this
235 * value is non-zero.
Simon Glasscdc133b2015-01-25 08:27:01 -0700236 * @per_child_platdata_auto_alloc_size: A bus likes to store information about
237 * its children. If non-zero this is the size of this data, to be allocated
238 * in the child's parent_platdata pointer.
Simon Glass0040b942014-07-23 06:55:17 -0600239 * @ops: Driver-specific operations. This is typically a list of function
Simon Glass6494d702014-02-26 15:59:18 -0700240 * pointers defined by the driver, to implement driver functions required by
241 * the uclass.
Simon Glass00606d72014-07-23 06:55:03 -0600242 * @flags: driver flags - see DM_FLAGS_...
Simon Glass6494d702014-02-26 15:59:18 -0700243 */
244struct driver {
245 char *name;
246 enum uclass_id id;
Simon Glassae7f4512014-06-11 23:29:45 -0600247 const struct udevice_id *of_match;
Heiko Schocher54c5d082014-05-22 12:43:05 +0200248 int (*bind)(struct udevice *dev);
249 int (*probe)(struct udevice *dev);
250 int (*remove)(struct udevice *dev);
251 int (*unbind)(struct udevice *dev);
252 int (*ofdata_to_platdata)(struct udevice *dev);
Simon Glass0118ce72015-01-25 08:27:03 -0700253 int (*child_post_bind)(struct udevice *dev);
Simon Glassa327dee2014-07-23 06:55:21 -0600254 int (*child_pre_probe)(struct udevice *dev);
255 int (*child_post_remove)(struct udevice *dev);
Simon Glass6494d702014-02-26 15:59:18 -0700256 int priv_auto_alloc_size;
257 int platdata_auto_alloc_size;
Simon Glasse59f4582014-07-23 06:55:20 -0600258 int per_child_auto_alloc_size;
Simon Glasscdc133b2015-01-25 08:27:01 -0700259 int per_child_platdata_auto_alloc_size;
Simon Glass6494d702014-02-26 15:59:18 -0700260 const void *ops; /* driver-specific operations */
Simon Glass00606d72014-07-23 06:55:03 -0600261 uint32_t flags;
Simon Glass6494d702014-02-26 15:59:18 -0700262};
263
264/* Declare a new U-Boot driver */
265#define U_BOOT_DRIVER(__name) \
266 ll_entry_declare(struct driver, __name, driver)
267
Simon Glassc57f8062016-07-17 15:23:15 -0600268/* Get a pointer to a given driver */
269#define DM_GET_DRIVER(__name) \
270 ll_entry_get(struct driver, __name, driver)
271
Simon Glass6494d702014-02-26 15:59:18 -0700272/**
273 * dev_get_platdata() - Get the platform data for a device
274 *
275 * This checks that dev is not NULL, but no other checks for now
276 *
277 * @dev Device to check
278 * @return platform data, or NULL if none
279 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600280void *dev_get_platdata(const struct udevice *dev);
Simon Glass6494d702014-02-26 15:59:18 -0700281
282/**
Simon Glasscdc133b2015-01-25 08:27:01 -0700283 * dev_get_parent_platdata() - Get the parent platform data for a device
284 *
285 * This checks that dev is not NULL, but no other checks for now
286 *
287 * @dev Device to check
288 * @return parent's platform data, or NULL if none
289 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600290void *dev_get_parent_platdata(const struct udevice *dev);
Simon Glasscdc133b2015-01-25 08:27:01 -0700291
292/**
Przemyslaw Marczak5eaed882015-04-15 13:07:18 +0200293 * dev_get_uclass_platdata() - Get the uclass platform data for a device
294 *
295 * This checks that dev is not NULL, but no other checks for now
296 *
297 * @dev Device to check
298 * @return uclass's platform data, or NULL if none
299 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600300void *dev_get_uclass_platdata(const struct udevice *dev);
Przemyslaw Marczak5eaed882015-04-15 13:07:18 +0200301
302/**
Simon Glass9a79f6e2015-09-28 23:32:02 -0600303 * dev_get_priv() - Get the private data for a device
304 *
305 * This checks that dev is not NULL, but no other checks for now
306 *
307 * @dev Device to check
308 * @return private data, or NULL if none
309 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600310void *dev_get_priv(const struct udevice *dev);
Simon Glass9a79f6e2015-09-28 23:32:02 -0600311
312/**
Simon Glassbcbe3d12015-09-28 23:32:01 -0600313 * dev_get_parent_priv() - Get the parent private data for a device
Simon Glasse59f4582014-07-23 06:55:20 -0600314 *
Simon Glassbcbe3d12015-09-28 23:32:01 -0600315 * The parent private data is data stored in the device but owned by the
316 * parent. For example, a USB device may have parent data which contains
317 * information about how to talk to the device over USB.
Simon Glasse59f4582014-07-23 06:55:20 -0600318 *
319 * This checks that dev is not NULL, but no other checks for now
320 *
321 * @dev Device to check
322 * @return parent data, or NULL if none
323 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600324void *dev_get_parent_priv(const struct udevice *dev);
Simon Glasse59f4582014-07-23 06:55:20 -0600325
326/**
Simon Glasse564f052015-03-05 12:25:20 -0700327 * dev_get_uclass_priv() - Get the private uclass data for a device
328 *
329 * This checks that dev is not NULL, but no other checks for now
330 *
331 * @dev Device to check
332 * @return private uclass data for this device, or NULL if none
333 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600334void *dev_get_uclass_priv(const struct udevice *dev);
Simon Glasse564f052015-03-05 12:25:20 -0700335
336/**
Simon Glass9a79f6e2015-09-28 23:32:02 -0600337 * struct dev_get_parent() - Get the parent of a device
338 *
339 * @child: Child to check
340 * @return parent of child, or NULL if this is the root device
341 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600342struct udevice *dev_get_parent(const struct udevice *child);
Simon Glass9a79f6e2015-09-28 23:32:02 -0600343
344/**
Simon Glass39de8432015-03-25 12:21:55 -0600345 * dev_get_driver_data() - get the driver data used to bind a device
Simon Glass2ef249b2014-11-11 10:46:18 -0700346 *
347 * When a device is bound using a device tree node, it matches a
Simon Glass8d1f3a92015-09-28 23:32:06 -0600348 * particular compatible string in struct udevice_id. This function
Simon Glass39de8432015-03-25 12:21:55 -0600349 * returns the associated data value for that compatible string. This is
350 * the 'data' field in struct udevice_id.
351 *
Simon Glass8d1f3a92015-09-28 23:32:06 -0600352 * As an example, consider this structure:
353 * static const struct udevice_id tegra_i2c_ids[] = {
354 * { .compatible = "nvidia,tegra114-i2c", .data = TYPE_114 },
355 * { .compatible = "nvidia,tegra20-i2c", .data = TYPE_STD },
356 * { .compatible = "nvidia,tegra20-i2c-dvc", .data = TYPE_DVC },
357 * { }
358 * };
359 *
360 * When driver model finds a driver for this it will store the 'data' value
361 * corresponding to the compatible string it matches. This function returns
362 * that value. This allows the driver to handle several variants of a device.
363 *
Simon Glass39de8432015-03-25 12:21:55 -0600364 * For USB devices, this is the driver_info field in struct usb_device_id.
365 *
366 * @dev: Device to check
Simon Glass8d1f3a92015-09-28 23:32:06 -0600367 * @return driver data (0 if none is provided)
Simon Glass2ef249b2014-11-11 10:46:18 -0700368 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600369ulong dev_get_driver_data(const struct udevice *dev);
Simon Glass2ef249b2014-11-11 10:46:18 -0700370
Przemyslaw Marczakcc73d372015-04-15 13:07:24 +0200371/**
372 * dev_get_driver_ops() - get the device's driver's operations
373 *
374 * This checks that dev is not NULL, and returns the pointer to device's
375 * driver's operations.
376 *
377 * @dev: Device to check
378 * @return void pointer to driver's operations or NULL for NULL-dev or NULL-ops
379 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600380const void *dev_get_driver_ops(const struct udevice *dev);
Przemyslaw Marczakcc73d372015-04-15 13:07:24 +0200381
Simon Glass8d1f3a92015-09-28 23:32:06 -0600382/**
Simon Glassb3670532015-01-25 08:27:04 -0700383 * device_get_uclass_id() - return the uclass ID of a device
384 *
385 * @dev: Device to check
386 * @return uclass ID for the device
387 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600388enum uclass_id device_get_uclass_id(const struct udevice *dev);
Simon Glassb3670532015-01-25 08:27:04 -0700389
Simon Glass8d1f3a92015-09-28 23:32:06 -0600390/**
Przemyslaw Marczakf9c370d2015-04-15 13:07:25 +0200391 * dev_get_uclass_name() - return the uclass name of a device
392 *
393 * This checks that dev is not NULL.
394 *
395 * @dev: Device to check
396 * @return pointer to the uclass name for the device
397 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600398const char *dev_get_uclass_name(const struct udevice *dev);
Przemyslaw Marczakf9c370d2015-04-15 13:07:25 +0200399
Simon Glass2ef249b2014-11-11 10:46:18 -0700400/**
Simon Glass997c87b2014-07-23 06:55:19 -0600401 * device_get_child() - Get the child of a device by index
402 *
403 * Returns the numbered child, 0 being the first. This does not use
404 * sequence numbers, only the natural order.
405 *
406 * @dev: Parent device to check
407 * @index: Child index
408 * @devp: Returns pointer to device
Simon Glass3f416f32015-07-27 15:47:19 -0600409 * @return 0 if OK, -ENODEV if no such device, other error if the device fails
410 * to probe
Simon Glass997c87b2014-07-23 06:55:19 -0600411 */
412int device_get_child(struct udevice *parent, int index, struct udevice **devp);
413
414/**
Lokesh Vutla240b9322019-09-04 16:01:26 +0530415 * device_get_child_count() - Get the available child count of a device
416 *
417 * Returns the number of children to a device.
418 *
419 * @parent: Parent device to check
420 */
421int device_get_child_count(struct udevice *parent);
422
423/**
Simon Glass5a66a8f2014-07-23 06:55:12 -0600424 * device_find_child_by_seq() - Find a child device based on a sequence
425 *
426 * This searches for a device with the given seq or req_seq.
427 *
428 * For seq, if an active device has this sequence it will be returned.
429 * If there is no such device then this will return -ENODEV.
430 *
431 * For req_seq, if a device (whether activated or not) has this req_seq
432 * value, that device will be returned. This is a strong indication that
433 * the device will receive that sequence when activated.
434 *
435 * @parent: Parent device
436 * @seq_or_req_seq: Sequence number to find (0=first)
437 * @find_req_seq: true to find req_seq, false to find seq
438 * @devp: Returns pointer to device (there is only one per for each seq).
439 * Set to NULL if none is found
440 * @return 0 if OK, -ve on error
441 */
442int device_find_child_by_seq(struct udevice *parent, int seq_or_req_seq,
443 bool find_req_seq, struct udevice **devp);
444
Simon Glass997c87b2014-07-23 06:55:19 -0600445/**
446 * device_get_child_by_seq() - Get a child device based on a sequence
447 *
448 * If an active device has this sequence it will be returned. If there is no
449 * such device then this will check for a device that is requesting this
450 * sequence.
451 *
452 * The device is probed to activate it ready for use.
453 *
454 * @parent: Parent device
455 * @seq: Sequence number to find (0=first)
456 * @devp: Returns pointer to device (there is only one per for each seq)
457 * Set to NULL if none is found
458 * @return 0 if OK, -ve on error
459 */
460int device_get_child_by_seq(struct udevice *parent, int seq,
461 struct udevice **devp);
462
463/**
464 * device_find_child_by_of_offset() - Find a child device based on FDT offset
465 *
466 * Locates a child device by its device tree offset.
467 *
468 * @parent: Parent device
469 * @of_offset: Device tree offset to find
470 * @devp: Returns pointer to device if found, otherwise this is set to NULL
471 * @return 0 if OK, -ve on error
472 */
473int device_find_child_by_of_offset(struct udevice *parent, int of_offset,
474 struct udevice **devp);
475
476/**
477 * device_get_child_by_of_offset() - Get a child device based on FDT offset
478 *
479 * Locates a child device by its device tree offset.
480 *
481 * The device is probed to activate it ready for use.
482 *
483 * @parent: Parent device
484 * @of_offset: Device tree offset to find
485 * @devp: Returns pointer to device if found, otherwise this is set to NULL
486 * @return 0 if OK, -ve on error
487 */
Simon Glass132f9bf2015-06-23 15:38:38 -0600488int device_get_child_by_of_offset(struct udevice *parent, int of_offset,
Simon Glass997c87b2014-07-23 06:55:19 -0600489 struct udevice **devp);
490
Simon Glassa8981d42014-10-13 23:41:49 -0600491/**
Jean-Jacques Hiblot7ec91812018-08-09 16:17:44 +0200492 * device_find_global_by_ofnode() - Get a device based on ofnode
Simon Glass26930472015-06-23 15:38:37 -0600493 *
Jean-Jacques Hiblot7ec91812018-08-09 16:17:44 +0200494 * Locates a device by its device tree ofnode, searching globally throughout
495 * the all driver model devices.
496 *
497 * The device is NOT probed
498 *
499 * @node: Device tree ofnode to find
500 * @devp: Returns pointer to device if found, otherwise this is set to NULL
501 * @return 0 if OK, -ve on error
502 */
503
504int device_find_global_by_ofnode(ofnode node, struct udevice **devp);
505
506/**
507 * device_get_global_by_ofnode() - Get a device based on ofnode
508 *
509 * Locates a device by its device tree ofnode, searching globally throughout
Simon Glass26930472015-06-23 15:38:37 -0600510 * the all driver model devices.
511 *
512 * The device is probed to activate it ready for use.
513 *
Jean-Jacques Hiblot7ec91812018-08-09 16:17:44 +0200514 * @node: Device tree ofnode to find
Simon Glass26930472015-06-23 15:38:37 -0600515 * @devp: Returns pointer to device if found, otherwise this is set to NULL
516 * @return 0 if OK, -ve on error
517 */
Jean-Jacques Hiblot7ec91812018-08-09 16:17:44 +0200518int device_get_global_by_ofnode(ofnode node, struct udevice **devp);
Simon Glass26930472015-06-23 15:38:37 -0600519
520/**
Simon Glassa8981d42014-10-13 23:41:49 -0600521 * device_find_first_child() - Find the first child of a device
522 *
523 * @parent: Parent device to search
524 * @devp: Returns first child device, or NULL if none
525 * @return 0
526 */
527int device_find_first_child(struct udevice *parent, struct udevice **devp);
528
529/**
Simon Glass3f416f32015-07-27 15:47:19 -0600530 * device_find_next_child() - Find the next child of a device
Simon Glassa8981d42014-10-13 23:41:49 -0600531 *
532 * @devp: Pointer to previous child device on entry. Returns pointer to next
533 * child device, or NULL if none
534 * @return 0
535 */
536int device_find_next_child(struct udevice **devp);
537
Peng Fanc9cac3f2015-02-10 14:46:32 +0800538/**
Simon Glasscdb6aa02018-10-01 12:22:07 -0600539 * device_find_first_inactive_child() - Find the first inactive child
540 *
541 * This is used to locate an existing child of a device which is of a given
542 * uclass.
543 *
Simon Glass3abe1112018-11-18 08:14:31 -0700544 * The device is NOT probed
545 *
Simon Glasscdb6aa02018-10-01 12:22:07 -0600546 * @parent: Parent device to search
547 * @uclass_id: Uclass to look for
548 * @devp: Returns device found, if any
549 * @return 0 if found, else -ENODEV
550 */
551int device_find_first_inactive_child(struct udevice *parent,
552 enum uclass_id uclass_id,
553 struct udevice **devp);
554
555/**
Simon Glass3abe1112018-11-18 08:14:31 -0700556 * device_find_first_child_by_uclass() - Find the first child of a device in uc
557 *
558 * @parent: Parent device to search
559 * @uclass_id: Uclass to look for
560 * @devp: Returns first child device in that uclass, if any
561 * @return 0 if found, else -ENODEV
562 */
563int device_find_first_child_by_uclass(struct udevice *parent,
564 enum uclass_id uclass_id,
565 struct udevice **devp);
566
567/**
568 * device_find_child_by_name() - Find a child by device name
569 *
570 * @parent: Parent device to search
571 * @name: Name to look for
572 * @devp: Returns device found, if any
573 * @return 0 if found, else -ENODEV
574 */
575int device_find_child_by_name(struct udevice *parent, const char *name,
576 struct udevice **devp);
577
578/**
Simon Glassc5785672015-03-25 12:21:57 -0600579 * device_has_children() - check if a device has any children
580 *
581 * @dev: Device to check
582 * @return true if the device has one or more children
583 */
Simon Glass9f15cc12018-10-01 12:22:06 -0600584bool device_has_children(const struct udevice *dev);
Simon Glassc5785672015-03-25 12:21:57 -0600585
586/**
587 * device_has_active_children() - check if a device has any active children
588 *
589 * @dev: Device to check
590 * @return true if the device has one or more children and at least one of
591 * them is active (probed).
592 */
593bool device_has_active_children(struct udevice *dev);
594
595/**
596 * device_is_last_sibling() - check if a device is the last sibling
597 *
598 * This function can be useful for display purposes, when special action needs
599 * to be taken when displaying the last sibling. This can happen when a tree
600 * view of devices is being displayed.
601 *
602 * @dev: Device to check
603 * @return true if there are no more siblings after this one - i.e. is it
604 * last in the list.
605 */
606bool device_is_last_sibling(struct udevice *dev);
607
Simon Glassf5c67ea2015-07-30 13:40:39 -0600608/**
609 * device_set_name() - set the name of a device
610 *
611 * This must be called in the device's bind() method and no later. Normally
612 * this is unnecessary but for probed devices which don't get a useful name
613 * this function can be helpful.
614 *
Simon Glassa2040fa2016-05-01 13:52:23 -0600615 * The name is allocated and will be freed automatically when the device is
616 * unbound.
617 *
Simon Glassf5c67ea2015-07-30 13:40:39 -0600618 * @dev: Device to update
619 * @name: New name (this string is allocated new memory and attached to
620 * the device)
621 * @return 0 if OK, -ENOMEM if there is not enough memory to allocate the
622 * string
623 */
624int device_set_name(struct udevice *dev, const char *name);
625
Bin Meng1e0f2262015-09-11 03:24:34 -0700626/**
Simon Glassa2040fa2016-05-01 13:52:23 -0600627 * device_set_name_alloced() - note that a device name is allocated
628 *
Simon Glassfd1c2d92016-07-04 11:58:15 -0600629 * This sets the DM_FLAG_NAME_ALLOCED flag for the device, so that when it is
Simon Glassa2040fa2016-05-01 13:52:23 -0600630 * unbound the name will be freed. This avoids memory leaks.
631 *
632 * @dev: Device to update
633 */
634void device_set_name_alloced(struct udevice *dev);
635
636/**
Simon Glass911f3ae2017-05-18 20:08:57 -0600637 * device_is_compatible() - check if the device is compatible with the compat
Mugunthan V N73443b92016-04-28 15:36:02 +0530638 *
639 * This allows to check whether the device is comaptible with the compat.
640 *
641 * @dev: udevice pointer for which compatible needs to be verified.
642 * @compat: Compatible string which needs to verified in the given
643 * device
644 * @return true if OK, false if the compatible is not found
645 */
Simon Glass911f3ae2017-05-18 20:08:57 -0600646bool device_is_compatible(struct udevice *dev, const char *compat);
Mugunthan V N73443b92016-04-28 15:36:02 +0530647
648/**
649 * of_machine_is_compatible() - check if the machine is compatible with
650 * the compat
651 *
652 * This allows to check whether the machine is comaptible with the compat.
653 *
654 * @compat: Compatible string which needs to verified
655 * @return true if OK, false if the compatible is not found
656 */
657bool of_machine_is_compatible(const char *compat);
658
659/**
Mario Sixe4c98a52018-06-26 08:46:50 +0200660 * dev_disable_by_path() - Disable a device given its device tree path
661 *
662 * @path: The device tree path identifying the device to be disabled
663 * @return 0 on success, -ve on error
664 */
665int dev_disable_by_path(const char *path);
666
667/**
668 * dev_enable_by_path() - Enable a device given its device tree path
669 *
670 * @path: The device tree path identifying the device to be enabled
671 * @return 0 on success, -ve on error
672 */
673int dev_enable_by_path(const char *path);
674
675/**
Bin Meng1e0f2262015-09-11 03:24:34 -0700676 * device_is_on_pci_bus - Test if a device is on a PCI bus
677 *
678 * @dev: device to test
679 * @return: true if it is on a PCI bus, false otherwise
680 */
681static inline bool device_is_on_pci_bus(struct udevice *dev)
682{
683 return device_get_uclass_id(dev->parent) == UCLASS_PCI;
684}
685
Simon Glass7aeac5b2015-11-08 23:47:52 -0700686/**
687 * device_foreach_child_safe() - iterate through child devices safely
688 *
689 * This allows the @pos child to be removed in the loop if required.
690 *
691 * @pos: struct udevice * for the current device
692 * @next: struct udevice * for the next device
693 * @parent: parent device to scan
694 */
695#define device_foreach_child_safe(pos, next, parent) \
696 list_for_each_entry_safe(pos, next, &parent->child_head, sibling_node)
697
Simon Glasscc7f66f2016-07-05 17:10:08 -0600698/**
Simon Glasse5f73902019-09-25 08:55:56 -0600699 * device_foreach_child() - iterate through child devices
700 *
701 * @pos: struct udevice * for the current device
702 * @parent: parent device to scan
703 */
704#define device_foreach_child(pos, parent) \
705 list_for_each_entry(pos, &parent->child_head, sibling_node)
706
707/**
Simon Glasscc7f66f2016-07-05 17:10:08 -0600708 * dm_scan_fdt_dev() - Bind child device in a the device tree
709 *
710 * This handles device which have sub-nodes in the device tree. It scans all
711 * sub-nodes and binds drivers for each node where a driver can be found.
712 *
713 * If this is called prior to relocation, only pre-relocation devices will be
714 * bound (those marked with u-boot,dm-pre-reloc in the device tree, or where
715 * the driver has the DM_FLAG_PRE_RELOC flag set). Otherwise, all devices will
716 * be bound.
717 *
718 * @dev: Device to scan
719 * @return 0 if OK, -ve on error
720 */
721int dm_scan_fdt_dev(struct udevice *dev);
722
Simon Glass42a8db52019-12-29 21:19:22 -0700723#include <dm/devres.h>
Masahiro Yamada2b07f682015-07-25 21:52:36 +0900724
Masahiro Yamadac898cba2017-09-26 11:58:29 +0900725/*
726 * REVISIT:
727 * remove the following after resolving conflicts with <linux/compat.h>
728 */
729#ifdef dev_dbg
730#undef dev_dbg
731#endif
732#ifdef dev_vdbg
733#undef dev_vdbg
734#endif
735#ifdef dev_info
736#undef dev_info
737#endif
738#ifdef dev_err
739#undef dev_err
740#endif
741#ifdef dev_warn
742#undef dev_warn
743#endif
744
745/*
746 * REVISIT:
747 * print device name like Linux
748 */
749#define dev_printk(dev, fmt, ...) \
750({ \
751 printk(fmt, ##__VA_ARGS__); \
752})
753
754#define __dev_printk(level, dev, fmt, ...) \
755({ \
756 if (level < CONFIG_VAL(LOGLEVEL)) \
757 dev_printk(dev, fmt, ##__VA_ARGS__); \
758})
759
760#define dev_emerg(dev, fmt, ...) \
761 __dev_printk(0, dev, fmt, ##__VA_ARGS__)
762#define dev_alert(dev, fmt, ...) \
763 __dev_printk(1, dev, fmt, ##__VA_ARGS__)
764#define dev_crit(dev, fmt, ...) \
765 __dev_printk(2, dev, fmt, ##__VA_ARGS__)
766#define dev_err(dev, fmt, ...) \
767 __dev_printk(3, dev, fmt, ##__VA_ARGS__)
768#define dev_warn(dev, fmt, ...) \
769 __dev_printk(4, dev, fmt, ##__VA_ARGS__)
770#define dev_notice(dev, fmt, ...) \
771 __dev_printk(5, dev, fmt, ##__VA_ARGS__)
772#define dev_info(dev, fmt, ...) \
773 __dev_printk(6, dev, fmt, ##__VA_ARGS__)
774
775#ifdef DEBUG
776#define dev_dbg(dev, fmt, ...) \
777 __dev_printk(7, dev, fmt, ##__VA_ARGS__)
778#else
779#define dev_dbg(dev, fmt, ...) \
780({ \
781 if (0) \
782 __dev_printk(7, dev, fmt, ##__VA_ARGS__); \
783})
784#endif
785
786#ifdef VERBOSE_DEBUG
787#define dev_vdbg dev_dbg
788#else
789#define dev_vdbg(dev, fmt, ...) \
790({ \
791 if (0) \
792 __dev_printk(7, dev, fmt, ##__VA_ARGS__); \
793})
794#endif
795
Simon Glass6494d702014-02-26 15:59:18 -0700796#endif