power-domain.h 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169
  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. *
  55. * Currently, the power domain API assumes that a single integer ID is enough
  56. * to identify and configure any power domain for any power domain provider. If
  57. * this assumption becomes invalid in the future, the struct could be expanded
  58. * to either (a) add more fields to allow power domain providers to store
  59. * additional information, or (b) replace the id field with an opaque pointer,
  60. * which the provider would dynamically allocate during its .of_xlate op, and
  61. * process during is .request op. This may require the addition of an extra op
  62. * to clean up the allocation.
  63. */
  64. struct power_domain {
  65. struct udevice *dev;
  66. /*
  67. * Written by of_xlate. We assume a single id is enough for now. In the
  68. * future, we might add more fields here.
  69. */
  70. unsigned long id;
  71. };
  72. /**
  73. * power_domain_get - Get/request the power domain for a device.
  74. *
  75. * This looks up and requests a power domain. Each device is assumed to have
  76. * a single (or, at least one) power domain associated with it somehow, and
  77. * that domain, or the first/default domain. The mapping of client device to
  78. * provider power domain may be via device-tree properties, board-provided
  79. * mapping tables, or some other mechanism.
  80. *
  81. * @dev: The client device.
  82. * @power_domain A pointer to a power domain struct to initialize.
  83. * @return 0 if OK, or a negative error code.
  84. */
  85. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  86. int power_domain_get(struct udevice *dev, struct power_domain *power_domain);
  87. #else
  88. static inline
  89. int power_domain_get(struct udevice *dev, struct power_domain *power_domain)
  90. {
  91. return -ENOSYS;
  92. }
  93. #endif
  94. /**
  95. * power_domain_get_by_index - Get the indexed power domain for a device.
  96. *
  97. * @dev: The client device.
  98. * @power_domain: A pointer to a power domain struct to initialize.
  99. * @index: Power domain index to be powered on.
  100. *
  101. * @return 0 if OK, or a negative error code.
  102. */
  103. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  104. int power_domain_get_by_index(struct udevice *dev,
  105. struct power_domain *power_domain, int index);
  106. #else
  107. static inline
  108. int power_domain_get_by_index(struct udevice *dev,
  109. struct power_domain *power_domain, int index)
  110. {
  111. return -ENOSYS;
  112. }
  113. #endif
  114. /**
  115. * power_domain_free - Free a previously requested power domain.
  116. *
  117. * @power_domain: A power domain struct that was previously successfully
  118. * requested by power_domain_get().
  119. * @return 0 if OK, or a negative error code.
  120. */
  121. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  122. int power_domain_free(struct power_domain *power_domain);
  123. #else
  124. static inline int power_domain_free(struct power_domain *power_domain)
  125. {
  126. return -ENOSYS;
  127. }
  128. #endif
  129. /**
  130. * power_domain_on - Enable power to a power domain.
  131. *
  132. * @power_domain: A power domain struct that was previously successfully
  133. * requested by power_domain_get().
  134. * @return 0 if OK, or a negative error code.
  135. */
  136. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  137. int power_domain_on(struct power_domain *power_domain);
  138. #else
  139. static inline int power_domain_on(struct power_domain *power_domain)
  140. {
  141. return -ENOSYS;
  142. }
  143. #endif
  144. /**
  145. * power_domain_off - Disable power ot a power domain.
  146. *
  147. * @power_domain: A power domain struct that was previously successfully
  148. * requested by power_domain_get().
  149. * @return 0 if OK, or a negative error code.
  150. */
  151. #if CONFIG_IS_ENABLED(POWER_DOMAIN)
  152. int power_domain_off(struct power_domain *power_domain);
  153. #else
  154. static inline int power_domain_off(struct power_domain *power_domain)
  155. {
  156. return -ENOSYS;
  157. }
  158. #endif
  159. #endif