device-internal.h 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235
  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. const struct driver_info *info, struct udevice **devp);
  79. /**
  80. * device_ofdata_to_platdata() - Read platform data for a device
  81. *
  82. * Read platform data for a device (typically from the device tree) so that
  83. * the information needed to probe the device is present.
  84. *
  85. * This may cause some others devices to be probed if this one depends on them,
  86. * e.g. a GPIO line will cause a GPIO device to be probed.
  87. *
  88. * All private data associated with the device is allocated.
  89. *
  90. * @dev: Pointer to device to process
  91. * @return 0 if OK, -ve on error
  92. */
  93. int device_ofdata_to_platdata(struct udevice *dev);
  94. /**
  95. * device_probe() - Probe a device, activating it
  96. *
  97. * Activate a device so that it is ready for use. All its parents are probed
  98. * first.
  99. *
  100. * @dev: Pointer to device to probe
  101. * @return 0 if OK, -ve on error
  102. */
  103. int device_probe(struct udevice *dev);
  104. /**
  105. * device_remove() - Remove a device, de-activating it
  106. *
  107. * De-activate a device so that it is no longer ready for use. All its
  108. * children are deactivated first.
  109. *
  110. * @dev: Pointer to device to remove
  111. * @flags: Flags for selective device removal (DM_REMOVE_...)
  112. * @return 0 if OK, -ve on error (an error here is normally a very bad thing)
  113. */
  114. #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
  115. int device_remove(struct udevice *dev, uint flags);
  116. #else
  117. static inline int device_remove(struct udevice *dev, uint flags) { return 0; }
  118. #endif
  119. /**
  120. * device_unbind() - Unbind a device, destroying it
  121. *
  122. * Unbind a device and remove all memory used by it
  123. *
  124. * @dev: Pointer to device to unbind
  125. * @return 0 if OK, -ve on error
  126. */
  127. #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
  128. int device_unbind(struct udevice *dev);
  129. #else
  130. static inline int device_unbind(struct udevice *dev) { return 0; }
  131. #endif
  132. #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
  133. void device_free(struct udevice *dev);
  134. #else
  135. static inline void device_free(struct udevice *dev) {}
  136. #endif
  137. /**
  138. * device_chld_unbind() - Unbind all device's children from the device if bound
  139. * to drv
  140. *
  141. * On error, the function continues to unbind all children, and reports the
  142. * first error.
  143. *
  144. * @dev: The device that is to be stripped of its children
  145. * @drv: The targeted driver
  146. * @return 0 on success, -ve on error
  147. */
  148. #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
  149. int device_chld_unbind(struct udevice *dev, struct driver *drv);
  150. #else
  151. static inline int device_chld_unbind(struct udevice *dev, struct driver *drv)
  152. {
  153. return 0;
  154. }
  155. #endif
  156. /**
  157. * device_chld_remove() - Stop all device's children
  158. * @dev: The device whose children are to be removed
  159. * @drv: The targeted driver
  160. * @flags: Flag, if this functions is called in the pre-OS stage
  161. * @return 0 on success, -ve on error
  162. */
  163. #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
  164. int device_chld_remove(struct udevice *dev, struct driver *drv,
  165. uint flags);
  166. #else
  167. static inline int device_chld_remove(struct udevice *dev, struct driver *drv,
  168. uint flags)
  169. {
  170. return 0;
  171. }
  172. #endif
  173. /**
  174. * simple_bus_translate() - translate a bus address to a system address
  175. *
  176. * This handles the 'ranges' property in a simple bus. It translates the
  177. * device address @addr to a system address using this property.
  178. *
  179. * @dev: Simple bus device (parent of target device)
  180. * @addr: Address to translate
  181. * @return new address
  182. */
  183. fdt_addr_t simple_bus_translate(struct udevice *dev, fdt_addr_t addr);
  184. /* Cast away any volatile pointer */
  185. #define DM_ROOT_NON_CONST (((gd_t *)gd)->dm_root)
  186. #define DM_UCLASS_ROOT_NON_CONST (((gd_t *)gd)->uclass_root)
  187. /* device resource management */
  188. #ifdef CONFIG_DEVRES
  189. /**
  190. * devres_release_probe - Release managed resources allocated after probing
  191. * @dev: Device to release resources for
  192. *
  193. * Release all resources allocated for @dev when it was probed or later.
  194. * This function is called on driver removal.
  195. */
  196. void devres_release_probe(struct udevice *dev);
  197. /**
  198. * devres_release_all - Release all managed resources
  199. * @dev: Device to release resources for
  200. *
  201. * Release all resources associated with @dev. This function is
  202. * called on driver unbinding.
  203. */
  204. void devres_release_all(struct udevice *dev);
  205. #else /* ! CONFIG_DEVRES */
  206. static inline void devres_release_probe(struct udevice *dev)
  207. {
  208. }
  209. static inline void devres_release_all(struct udevice *dev)
  210. {
  211. }
  212. #endif /* ! CONFIG_DEVRES */
  213. #endif