power-domain.h 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211
  1. /* SPDX-License-Identifier: GPL-2.0 */
  2. /*
  3. * Copyright (c) 2016, NVIDIA CORPORATION.
  4. */
  5. #ifndef _POWER_DOMAIN_H
  6. #define _POWER_DOMAIN_H
  7. /**
  8. * A power domain is a portion of an SoC or chip that is powered by a
  9. * switchable source of power. In many cases, software has control over the
  10. * power domain, and can turn the power source on or off. This is typically
  11. * done to save power by powering off unused devices, or to enable software
  12. * sequencing of initial powerup at boot. This API provides a means for
  13. * drivers to turn power domains on and off.
  14. *
  15. * A driver that implements UCLASS_POWER_DOMAIN is a power domain controller or
  16. * provider. A controller will often implement multiple separate power domains,
  17. * since the hardware it manages often has this capability.
  18. * power-domain-uclass.h describes the interface which power domain controllers
  19. * must implement.
  20. *
  21. * Depending on the power domain controller hardware, changing the state of a
  22. * power domain may require performing related operations on other resources.
  23. * For example, some power domains may require certain clocks to be enabled
  24. * whenever the power domain is powered on, or during the time when the power
  25. * domain is transitioning state. These details are implementation-specific
  26. * and should ideally be encapsulated entirely within the provider driver, or
  27. * configured through mechanisms (e.g. device tree) that do not require client
  28. * drivers to provide extra configuration information.
  29. *
  30. * Power domain consumers/clients are the drivers for HW modules within the
  31. * power domain. This header file describes the API used by those drivers.
  32. *
  33. * In many cases, a single complex IO controller (e.g. a PCIe controller) will
  34. * be the sole logic contained within a power domain. In such cases, it is
  35. * logical for the relevant device driver to directly control that power
  36. * domain. In other cases, multiple controllers, each with their own driver,
  37. * may be contained in a single power domain. Any logic require to co-ordinate
  38. * between drivers for these multiple controllers is beyond the scope of this
  39. * API at present. Equally, this API does not define or implement any policy
  40. * by which power domains are managed.
  41. */
  42. struct udevice;
  43. /**
  44. * struct power_domain - A handle to (allowing control of) a single power domain.
  45. *
  46. * Clients provide storage for power domain handles. The content of the
  47. * structure is managed solely by the power domain API and power domain
  48. * drivers. A power domain struct is initialized by "get"ing the power domain
  49. * struct. The power domain struct is passed to all other power domain APIs to
  50. * identify which power domain to operate upon.
  51. *
  52. * @dev: The device which implements the power domain.
  53. * @id: The power domain ID within the provider.
  54. * @priv: Private data corresponding to each power domain.
  55. */
  56. struct power_domain {
  57. struct udevice *dev;
  58. unsigned long id;
  59. void *priv;
  60. };
  61. /**
  62. * power_domain_get - Get/request the power domain for a device.
  63. *
  64. * This looks up and requests a power domain. Each device is assumed to have
  65. * a single (or, at least one) power domain associated with it somehow, and
  66. * that domain, or the first/default domain. The mapping of client device to
  67. * provider power domain may be via device-tree properties, board-provided
  68. * mapping tables, or some other mechanism.
  69. *
  70. * @dev: The client device.
  71. * @power_domain A pointer to a power domain struct to initialize.
  72. * Return: 0 if OK, or a negative error code.
  73. */
  74. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  75. int power_domain_get(struct udevice *dev, struct power_domain *power_domain);
  76. #else
  77. static inline
  78. int power_domain_get(struct udevice *dev, struct power_domain *power_domain)
  79. {
  80. return -ENOSYS;
  81. }
  82. #endif
  83. /**
  84. * power_domain_get_by_index - Get the indexed power domain for a device.
  85. *
  86. * @dev: The client device.
  87. * @power_domain: A pointer to a power domain struct to initialize.
  88. * @index: Power domain index to be powered on.
  89. *
  90. * Return: 0 if OK, or a negative error code.
  91. */
  92. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  93. int power_domain_get_by_index(struct udevice *dev,
  94. struct power_domain *power_domain, int index);
  95. #else
  96. static inline
  97. int power_domain_get_by_index(struct udevice *dev,
  98. struct power_domain *power_domain, int index)
  99. {
  100. return -ENOSYS;
  101. }
  102. #endif
  103. /**
  104. * power_domain_get_by_name - Get the named power domain for a device.
  105. *
  106. * @dev: The client device.
  107. * @power_domain: A pointer to a power domain struct to initialize.
  108. * @name: Power domain name to be powered on.
  109. *
  110. * Return: 0 if OK, or a negative error code.
  111. */
  112. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  113. int power_domain_get_by_name(struct udevice *dev,
  114. struct power_domain *power_domain, const char *name);
  115. #else
  116. static inline
  117. int power_domain_get_by_name(struct udevice *dev,
  118. struct power_domain *power_domain, const char *name)
  119. {
  120. return -ENOSYS;
  121. }
  122. #endif
  123. /**
  124. * power_domain_free - Free a previously requested power domain.
  125. *
  126. * @power_domain: A power domain struct that was previously successfully
  127. * requested by power_domain_get().
  128. * Return: 0 if OK, or a negative error code.
  129. */
  130. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  131. int power_domain_free(struct power_domain *power_domain);
  132. #else
  133. static inline int power_domain_free(struct power_domain *power_domain)
  134. {
  135. return -ENOSYS;
  136. }
  137. #endif
  138. /**
  139. * power_domain_on - Enable power to a power domain.
  140. *
  141. * @power_domain: A power domain struct that was previously successfully
  142. * requested by power_domain_get().
  143. * Return: 0 if OK, or a negative error code.
  144. */
  145. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  146. int power_domain_on(struct power_domain *power_domain);
  147. #else
  148. static inline int power_domain_on(struct power_domain *power_domain)
  149. {
  150. return -ENOSYS;
  151. }
  152. #endif
  153. /**
  154. * power_domain_off - Disable power to a power domain.
  155. *
  156. * @power_domain: A power domain struct that was previously successfully
  157. * requested by power_domain_get().
  158. * Return: 0 if OK, or a negative error code.
  159. */
  160. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  161. int power_domain_off(struct power_domain *power_domain);
  162. #else
  163. static inline int power_domain_off(struct power_domain *power_domain)
  164. {
  165. return -ENOSYS;
  166. }
  167. #endif
  168. /**
  169. * dev_power_domain_on - Enable power domains for a device .
  170. *
  171. * @dev: The client device.
  172. *
  173. * Return: 0 if OK, or a negative error code.
  174. */
  175. #if CONFIG_IS_ENABLED(OF_REAL) && CONFIG_IS_ENABLED(POWER_DOMAIN)
  176. int dev_power_domain_on(struct udevice *dev);
  177. #else
  178. static inline int dev_power_domain_on(struct udevice *dev)
  179. {
  180. return 0;
  181. }
  182. #endif
  183. /**
  184. * dev_power_domain_off - Disable power domains for a device .
  185. *
  186. * @dev: The client device.
  187. *
  188. * Return: 0 if OK, or a negative error code.
  189. */
  190. #if CONFIG_IS_ENABLED(OF_REAL) && CONFIG_IS_ENABLED(POWER_DOMAIN)
  191. int dev_power_domain_off(struct udevice *dev);
  192. #else
  193. static inline int dev_power_domain_off(struct udevice *dev)
  194. {
  195. return 0;
  196. }
  197. #endif
  198. #endif