device-internal.h 7.3 KB

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