1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * Copyright (c) 2016, NVIDIA CORPORATION. 4 */ 5 6 #ifndef _POWER_DOMAIN_H 7 #define _POWER_DOMAIN_H 8 9 /** 10 * A power domain is a portion of an SoC or chip that is powered by a 11 * switchable source of power. In many cases, software has control over the 12 * power domain, and can turn the power source on or off. This is typically 13 * done to save power by powering off unused devices, or to enable software 14 * sequencing of initial powerup at boot. This API provides a means for 15 * drivers to turn power domains on and off. 16 * 17 * A driver that implements UCLASS_POWER_DOMAIN is a power domain controller or 18 * provider. A controller will often implement multiple separate power domains, 19 * since the hardware it manages often has this capability. 20 * power-domain-uclass.h describes the interface which power domain controllers 21 * must implement. 22 * 23 * Depending on the power domain controller hardware, changing the state of a 24 * power domain may require performing related operations on other resources. 25 * For example, some power domains may require certain clocks to be enabled 26 * whenever the power domain is powered on, or during the time when the power 27 * domain is transitioning state. These details are implementation-specific 28 * and should ideally be encapsulated entirely within the provider driver, or 29 * configured through mechanisms (e.g. device tree) that do not require client 30 * drivers to provide extra configuration information. 31 * 32 * Power domain consumers/clients are the drivers for HW modules within the 33 * power domain. This header file describes the API used by those drivers. 34 * 35 * In many cases, a single complex IO controller (e.g. a PCIe controller) will 36 * be the sole logic contained within a power domain. In such cases, it is 37 * logical for the relevant device driver to directly control that power 38 * domain. In other cases, multiple controllers, each with their own driver, 39 * may be contained in a single power domain. Any logic require to co-ordinate 40 * between drivers for these multiple controllers is beyond the scope of this 41 * API at present. Equally, this API does not define or implement any policy 42 * by which power domains are managed. 43 */ 44 45 struct udevice; 46 47 /** 48 * struct power_domain - A handle to (allowing control of) a single power domain. 49 * 50 * Clients provide storage for power domain handles. The content of the 51 * structure is managed solely by the power domain API and power domain 52 * drivers. A power domain struct is initialized by "get"ing the power domain 53 * struct. The power domain struct is passed to all other power domain APIs to 54 * identify which power domain to operate upon. 55 * 56 * @dev: The device which implements the power domain. 57 * @id: The power domain ID within the provider. 58 * 59 * Currently, the power domain API assumes that a single integer ID is enough 60 * to identify and configure any power domain for any power domain provider. If 61 * this assumption becomes invalid in the future, the struct could be expanded 62 * to either (a) add more fields to allow power domain providers to store 63 * additional information, or (b) replace the id field with an opaque pointer, 64 * which the provider would dynamically allocate during its .of_xlate op, and 65 * process during is .request op. This may require the addition of an extra op 66 * to clean up the allocation. 67 */ 68 struct power_domain { 69 struct udevice *dev; 70 /* 71 * Written by of_xlate. We assume a single id is enough for now. In the 72 * future, we might add more fields here. 73 */ 74 unsigned long id; 75 }; 76 77 /** 78 * power_domain_get - Get/request the power domain for a device. 79 * 80 * This looks up and requests a power domain. Each device is assumed to have 81 * a single (or, at least one) power domain associated with it somehow, and 82 * that domain, or the first/default domain. The mapping of client device to 83 * provider power domain may be via device-tree properties, board-provided 84 * mapping tables, or some other mechanism. 85 * 86 * @dev: The client device. 87 * @power_domain A pointer to a power domain struct to initialize. 88 * @return 0 if OK, or a negative error code. 89 */ 90 #if CONFIG_IS_ENABLED(POWER_DOMAIN) 91 int power_domain_get(struct udevice *dev, struct power_domain *power_domain); 92 #else 93 static inline 94 int power_domain_get(struct udevice *dev, struct power_domain *power_domain) 95 { 96 return -ENOSYS; 97 } 98 #endif 99 100 /** 101 * power_domain_get_by_index - Get the indexed power domain for a device. 102 * 103 * @dev: The client device. 104 * @power_domain: A pointer to a power domain struct to initialize. 105 * @index: Power domain index to be powered on. 106 * 107 * @return 0 if OK, or a negative error code. 108 */ 109 #if CONFIG_IS_ENABLED(POWER_DOMAIN) 110 int power_domain_get_by_index(struct udevice *dev, 111 struct power_domain *power_domain, int index); 112 #else 113 static inline 114 int power_domain_get_by_index(struct udevice *dev, 115 struct power_domain *power_domain, int index) 116 { 117 return -ENOSYS; 118 } 119 #endif 120 121 /** 122 * power_domain_free - Free a previously requested power domain. 123 * 124 * @power_domain: A power domain struct that was previously successfully 125 * requested by power_domain_get(). 126 * @return 0 if OK, or a negative error code. 127 */ 128 #if CONFIG_IS_ENABLED(POWER_DOMAIN) 129 int power_domain_free(struct power_domain *power_domain); 130 #else 131 static inline int power_domain_free(struct power_domain *power_domain) 132 { 133 return -ENOSYS; 134 } 135 #endif 136 137 /** 138 * power_domain_on - Enable power to a power domain. 139 * 140 * @power_domain: A power domain struct that was previously successfully 141 * requested by power_domain_get(). 142 * @return 0 if OK, or a negative error code. 143 */ 144 #if CONFIG_IS_ENABLED(POWER_DOMAIN) 145 int power_domain_on(struct power_domain *power_domain); 146 #else 147 static inline int power_domain_on(struct power_domain *power_domain) 148 { 149 return -ENOSYS; 150 } 151 #endif 152 153 /** 154 * power_domain_off - Disable power ot 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 #endif 170