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
power_domain_get_by_index(struct udevice * dev,struct power_domain * power_domain,int index)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
power_domain_get_by_name(struct udevice * dev,struct power_domain * power_domain,const char * name)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
dev_power_domain_on(struct udevice * dev)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
dev_power_domain_off(struct udevice * dev)190 static inline int dev_power_domain_off(struct udevice *dev)
191 {
192 return 0;
193 }
194 #endif
195
196 #endif
197