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 * @priv: Private data corresponding to each power domain.
59 */
60 struct power_domain {
61 struct udevice *dev;
62 unsigned long id;
63 void *priv;
64 };
65
66 /**
67 * power_domain_get - Get/request the power domain for a device.
68 *
69 * This looks up and requests a power domain. Each device is assumed to have
70 * a single (or, at least one) power domain associated with it somehow, and
71 * that domain, or the first/default domain. The mapping of client device to
72 * provider power domain may be via device-tree properties, board-provided
73 * mapping tables, or some other mechanism.
74 *
75 * @dev: The client device.
76 * @power_domain A pointer to a power domain struct to initialize.
77 * Return: 0 if OK, or a negative error code.
78 */
79 #if CONFIG_IS_ENABLED(POWER_DOMAIN)
80 int power_domain_get(struct udevice *dev, struct power_domain *power_domain);
81 #else
82 static inline
power_domain_get(struct udevice * dev,struct power_domain * power_domain)83 int power_domain_get(struct udevice *dev, struct power_domain *power_domain)
84 {
85 return -ENOSYS;
86 }
87 #endif
88
89 /**
90 * power_domain_get_by_index - Get the indexed power domain for a device.
91 *
92 * @dev: The client device.
93 * @power_domain: A pointer to a power domain struct to initialize.
94 * @index: Power domain index to be powered on.
95 *
96 * Return: 0 if OK, or a negative error code.
97 */
98 #if CONFIG_IS_ENABLED(POWER_DOMAIN)
99 int power_domain_get_by_index(struct udevice *dev,
100 struct power_domain *power_domain, int index);
101 #else
102 static inline
power_domain_get_by_index(struct udevice * dev,struct power_domain * power_domain,int index)103 int power_domain_get_by_index(struct udevice *dev,
104 struct power_domain *power_domain, int index)
105 {
106 return -ENOSYS;
107 }
108 #endif
109
110 /**
111 * power_domain_get_by_name - Get the named power domain for a device.
112 *
113 * @dev: The client device.
114 * @power_domain: A pointer to a power domain struct to initialize.
115 * @name: Power domain name to be powered on.
116 *
117 * Return: 0 if OK, or a negative error code.
118 */
119 #if CONFIG_IS_ENABLED(POWER_DOMAIN)
120 int power_domain_get_by_name(struct udevice *dev,
121 struct power_domain *power_domain, const char *name);
122 #else
123 static inline
power_domain_get_by_name(struct udevice * dev,struct power_domain * power_domain,const char * name)124 int power_domain_get_by_name(struct udevice *dev,
125 struct power_domain *power_domain, const char *name)
126 {
127 return -ENOSYS;
128 }
129 #endif
130
131 /**
132 * power_domain_free - Free a previously requested power domain.
133 *
134 * @power_domain: A power domain struct that was previously successfully
135 * requested by power_domain_get().
136 * Return: 0 if OK, or a negative error code.
137 */
138 #if CONFIG_IS_ENABLED(POWER_DOMAIN)
139 int power_domain_free(struct power_domain *power_domain);
140 #else
power_domain_free(struct power_domain * power_domain)141 static inline int power_domain_free(struct power_domain *power_domain)
142 {
143 return -ENOSYS;
144 }
145 #endif
146
147 /**
148 * power_domain_on - Enable power to a power domain.
149 *
150 * @power_domain: A power domain struct that was previously successfully
151 * requested by power_domain_get().
152 * Return: 0 if OK, or a negative error code.
153 */
154 #if CONFIG_IS_ENABLED(POWER_DOMAIN)
155 int power_domain_on(struct power_domain *power_domain);
156 #else
power_domain_on(struct power_domain * power_domain)157 static inline int power_domain_on(struct power_domain *power_domain)
158 {
159 return -ENOSYS;
160 }
161 #endif
162
163 /**
164 * power_domain_off - Disable power to a power domain.
165 *
166 * @power_domain: A power domain struct that was previously successfully
167 * requested by power_domain_get().
168 * Return: 0 if OK, or a negative error code.
169 */
170 #if CONFIG_IS_ENABLED(POWER_DOMAIN)
171 int power_domain_off(struct power_domain *power_domain);
172 #else
power_domain_off(struct power_domain * power_domain)173 static inline int power_domain_off(struct power_domain *power_domain)
174 {
175 return -ENOSYS;
176 }
177 #endif
178
179 /**
180 * dev_power_domain_on - Enable 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_REAL) && CONFIG_IS_ENABLED(POWER_DOMAIN)
187 int dev_power_domain_on(struct udevice *dev);
188 #else
dev_power_domain_on(struct udevice * dev)189 static inline int dev_power_domain_on(struct udevice *dev)
190 {
191 return 0;
192 }
193 #endif
194
195 /**
196 * dev_power_domain_off - Disable power domains for a device .
197 *
198 * @dev: The client device.
199 *
200 * Return: 0 if OK, or a negative error code.
201 */
202 #if CONFIG_IS_ENABLED(OF_REAL) && CONFIG_IS_ENABLED(POWER_DOMAIN)
203 int dev_power_domain_off(struct udevice *dev);
204 #else
dev_power_domain_off(struct udevice * dev)205 static inline int dev_power_domain_off(struct udevice *dev)
206 {
207 return 0;
208 }
209 #endif
210
211 #endif
212