device-internal.h 6.5 KB

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