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