xref: /openbmc/u-boot/include/dm/device-internal.h (revision 1d6edcbf)
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  * Marek Vasut <marex@denx.de>
8  */
9 
10 #ifndef _DM_DEVICE_INTERNAL_H
11 #define _DM_DEVICE_INTERNAL_H
12 
13 #include <dm/ofnode.h>
14 
15 struct device_node;
16 struct udevice;
17 
18 /**
19  * device_bind() - Create a device and bind it to a driver
20  *
21  * Called to set up a new device attached to a driver. The device will either
22  * have platdata, or a device tree node which can be used to create the
23  * platdata.
24  *
25  * Once bound a device exists but is not yet active until device_probe() is
26  * called.
27  *
28  * @parent: Pointer to device's parent, under which this driver will exist
29  * @drv: Device's driver
30  * @name: Name of device (e.g. device tree node name)
31  * @platdata: Pointer to data for this device - the structure is device-
32  * specific but may include the device's I/O address, etc.. This is NULL for
33  * devices which use device tree.
34  * @of_offset: Offset of device tree node for this device. This is -1 for
35  * devices which don't use device tree.
36  * @devp: if non-NULL, returns a pointer to the bound device
37  * @return 0 if OK, -ve on error
38  */
39 int device_bind(struct udevice *parent, const struct driver *drv,
40 		const char *name, void *platdata, int of_offset,
41 		struct udevice **devp);
42 
43 int device_bind_ofnode(struct udevice *parent, const struct driver *drv,
44 		       const char *name, void *platdata, ofnode node,
45 		       struct udevice **devp);
46 
47 /**
48  * device_bind_with_driver_data() - Create a device and bind it to a driver
49  *
50  * Called to set up a new device attached to a driver, in the case where the
51  * driver was matched to the device by means of a match table that provides
52  * driver_data.
53  *
54  * Once bound a device exists but is not yet active until device_probe() is
55  * called.
56  *
57  * @parent: Pointer to device's parent, under which this driver will exist
58  * @drv: Device's driver
59  * @name: Name of device (e.g. device tree node name)
60  * @driver_data: The driver_data field from the driver's match table.
61  * @node: Device tree node for this device. This is invalid for devices which
62  * don't use device tree.
63  * @devp: if non-NULL, returns a pointer to the bound device
64  * @return 0 if OK, -ve on error
65  */
66 int device_bind_with_driver_data(struct udevice *parent,
67 				 const struct driver *drv, const char *name,
68 				 ulong driver_data, ofnode node,
69 				 struct udevice **devp);
70 /**
71  * device_bind_by_name: Create a device and bind it to a driver
72  *
73  * This is a helper function used to bind devices which do not use device
74  * tree.
75  *
76  * @parent: Pointer to device's parent
77  * @pre_reloc_only: If true, bind the driver only if its DM_FLAG_PRE_RELOC flag
78  * is set. If false bind the driver always.
79  * @info: Name and platdata for this device
80  * @devp: if non-NULL, returns a pointer to the bound device
81  * @return 0 if OK, -ve on error
82  */
83 int device_bind_by_name(struct udevice *parent, bool pre_reloc_only,
84 			const struct driver_info *info, struct udevice **devp);
85 
86 /**
87  * device_probe() - Probe a device, activating it
88  *
89  * Activate a device so that it is ready for use. All its parents are probed
90  * first.
91  *
92  * @dev: Pointer to device to probe
93  * @return 0 if OK, -ve on error
94  */
95 int device_probe(struct udevice *dev);
96 
97 /**
98  * device_remove() - Remove a device, de-activating it
99  *
100  * De-activate a device so that it is no longer ready for use. All its
101  * children are deactivated first.
102  *
103  * @dev: Pointer to device to remove
104  * @flags: Flags for selective device removal (DM_REMOVE_...)
105  * @return 0 if OK, -ve on error (an error here is normally a very bad thing)
106  */
107 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
108 int device_remove(struct udevice *dev, uint flags);
109 #else
device_remove(struct udevice * dev,uint flags)110 static inline int device_remove(struct udevice *dev, uint flags) { return 0; }
111 #endif
112 
113 /**
114  * device_unbind() - Unbind a device, destroying it
115  *
116  * Unbind a device and remove all memory used by it
117  *
118  * @dev: Pointer to device to unbind
119  * @return 0 if OK, -ve on error
120  */
121 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
122 int device_unbind(struct udevice *dev);
123 #else
device_unbind(struct udevice * dev)124 static inline int device_unbind(struct udevice *dev) { return 0; }
125 #endif
126 
127 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
128 void device_free(struct udevice *dev);
129 #else
device_free(struct udevice * dev)130 static inline void device_free(struct udevice *dev) {}
131 #endif
132 
133 /**
134  * device_chld_unbind() - Unbind all device's children from the device if bound
135  *			  to drv
136  *
137  * On error, the function continues to unbind all children, and reports the
138  * first error.
139  *
140  * @dev:	The device that is to be stripped of its children
141  * @drv:	The targeted driver
142  * @return 0 on success, -ve on error
143  */
144 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
145 int device_chld_unbind(struct udevice *dev, struct driver *drv);
146 #else
device_chld_unbind(struct udevice * dev,struct driver * drv)147 static inline int device_chld_unbind(struct udevice *dev, struct driver *drv)
148 {
149 	return 0;
150 }
151 #endif
152 
153 /**
154  * device_chld_remove() - Stop all device's children
155  * @dev:	The device whose children are to be removed
156  * @drv:	The targeted driver
157  * @flags:	Flag, if this functions is called in the pre-OS stage
158  * @return 0 on success, -ve on error
159  */
160 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
161 int device_chld_remove(struct udevice *dev, struct driver *drv,
162 		       uint flags);
163 #else
device_chld_remove(struct udevice * dev,struct driver * drv,uint flags)164 static inline int device_chld_remove(struct udevice *dev, struct driver *drv,
165 				     uint flags)
166 {
167 	return 0;
168 }
169 #endif
170 
171 /**
172  * simple_bus_translate() - translate a bus address to a system address
173  *
174  * This handles the 'ranges' property in a simple bus. It translates the
175  * device address @addr to a system address using this property.
176  *
177  * @dev:	Simple bus device (parent of target device)
178  * @addr:	Address to translate
179  * @return new address
180  */
181 fdt_addr_t simple_bus_translate(struct udevice *dev, fdt_addr_t addr);
182 
183 /* Cast away any volatile pointer */
184 #define DM_ROOT_NON_CONST		(((gd_t *)gd)->dm_root)
185 #define DM_UCLASS_ROOT_NON_CONST	(((gd_t *)gd)->uclass_root)
186 
187 /* device resource management */
188 #ifdef CONFIG_DEVRES
189 
190 /**
191  * devres_release_probe - Release managed resources allocated after probing
192  * @dev: Device to release resources for
193  *
194  * Release all resources allocated for @dev when it was probed or later.
195  * This function is called on driver removal.
196  */
197 void devres_release_probe(struct udevice *dev);
198 
199 /**
200  * devres_release_all - Release all managed resources
201  * @dev: Device to release resources for
202  *
203  * Release all resources associated with @dev.  This function is
204  * called on driver unbinding.
205  */
206 void devres_release_all(struct udevice *dev);
207 
208 #else /* ! CONFIG_DEVRES */
209 
devres_release_probe(struct udevice * dev)210 static inline void devres_release_probe(struct udevice *dev)
211 {
212 }
213 
devres_release_all(struct udevice * dev)214 static inline void devres_release_all(struct udevice *dev)
215 {
216 }
217 
218 #endif /* ! CONFIG_DEVRES */
219 #endif
220