power-domain.h 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192
  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_free - Free a previously requested power domain.
  105. *
  106. * @power_domain: A power domain struct that was previously successfully
  107. * requested by power_domain_get().
  108. * @return 0 if OK, or a negative error code.
  109. */
  110. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  111. int power_domain_free(struct power_domain *power_domain);
  112. #else
  113. static inline int power_domain_free(struct power_domain *power_domain)
  114. {
  115. return -ENOSYS;
  116. }
  117. #endif
  118. /**
  119. * power_domain_on - Enable power to a power domain.
  120. *
  121. * @power_domain: A power domain struct that was previously successfully
  122. * requested by power_domain_get().
  123. * @return 0 if OK, or a negative error code.
  124. */
  125. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  126. int power_domain_on(struct power_domain *power_domain);
  127. #else
  128. static inline int power_domain_on(struct power_domain *power_domain)
  129. {
  130. return -ENOSYS;
  131. }
  132. #endif
  133. /**
  134. * power_domain_off - Disable power to a power domain.
  135. *
  136. * @power_domain: A power domain struct that was previously successfully
  137. * requested by power_domain_get().
  138. * @return 0 if OK, or a negative error code.
  139. */
  140. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  141. int power_domain_off(struct power_domain *power_domain);
  142. #else
  143. static inline int power_domain_off(struct power_domain *power_domain)
  144. {
  145. return -ENOSYS;
  146. }
  147. #endif
  148. /**
  149. * dev_power_domain_on - Enable power domains for a device .
  150. *
  151. * @dev: The client device.
  152. *
  153. * @return 0 if OK, or a negative error code.
  154. */
  155. #if (CONFIG_IS_ENABLED(OF_CONTROL) && !CONFIG_IS_ENABLED(OF_PLATDATA)) && \
  156. CONFIG_IS_ENABLED(POWER_DOMAIN)
  157. int dev_power_domain_on(struct udevice *dev);
  158. #else
  159. static inline int dev_power_domain_on(struct udevice *dev)
  160. {
  161. return 0;
  162. }
  163. #endif
  164. /**
  165. * dev_power_domain_off - Disable power domains for a device .
  166. *
  167. * @dev: The client device.
  168. *
  169. * @return 0 if OK, or a negative error code.
  170. */
  171. #if (CONFIG_IS_ENABLED(OF_CONTROL) && !CONFIG_IS_ENABLED(OF_PLATDATA)) && \
  172. CONFIG_IS_ENABLED(POWER_DOMAIN)
  173. int dev_power_domain_off(struct udevice *dev);
  174. #else
  175. static inline int dev_power_domain_off(struct udevice *dev)
  176. {
  177. return 0;
  178. }
  179. #endif
  180. #endif