blob: 00996057b0d4f8fcf86e369baab01c371a3f9aca [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001/* SPDX-License-Identifier: GPL-2.0 */
Stephen Warren61f5ddc2016-07-13 13:45:31 -06002/*
3 * Copyright (c) 2016, NVIDIA CORPORATION.
Stephen Warren61f5ddc2016-07-13 13:45:31 -06004 */
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
45struct 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 */
68struct 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 */
Peng Fan58d3de12018-07-27 10:20:36 +080090#if CONFIG_IS_ENABLED(POWER_DOMAIN)
Stephen Warren61f5ddc2016-07-13 13:45:31 -060091int power_domain_get(struct udevice *dev, struct power_domain *power_domain);
Peng Fan58d3de12018-07-27 10:20:36 +080092#else
93static inline
94int power_domain_get(struct udevice *dev, struct power_domain *power_domain)
95{
96 return -ENOSYS;
97}
98#endif
Stephen Warren61f5ddc2016-07-13 13:45:31 -060099
100/**
Lokesh Vutla2618cf32018-08-27 15:57:44 +0530101 * 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)
110int power_domain_get_by_index(struct udevice *dev,
111 struct power_domain *power_domain, int index);
112#else
113static inline
114int 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/**
Stephen Warren61f5ddc2016-07-13 13:45:31 -0600122 * 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 */
Peng Fan58d3de12018-07-27 10:20:36 +0800128#if CONFIG_IS_ENABLED(POWER_DOMAIN)
Stephen Warren61f5ddc2016-07-13 13:45:31 -0600129int power_domain_free(struct power_domain *power_domain);
Peng Fan58d3de12018-07-27 10:20:36 +0800130#else
131static inline int power_domain_free(struct power_domain *power_domain)
132{
133 return -ENOSYS;
134}
135#endif
Stephen Warren61f5ddc2016-07-13 13:45:31 -0600136
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 */
Peng Fan58d3de12018-07-27 10:20:36 +0800144#if CONFIG_IS_ENABLED(POWER_DOMAIN)
Stephen Warren61f5ddc2016-07-13 13:45:31 -0600145int power_domain_on(struct power_domain *power_domain);
Peng Fan58d3de12018-07-27 10:20:36 +0800146#else
147static inline int power_domain_on(struct power_domain *power_domain)
148{
149 return -ENOSYS;
150}
151#endif
Stephen Warren61f5ddc2016-07-13 13:45:31 -0600152
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 */
Peng Fan58d3de12018-07-27 10:20:36 +0800160#if CONFIG_IS_ENABLED(POWER_DOMAIN)
Stephen Warren61f5ddc2016-07-13 13:45:31 -0600161int power_domain_off(struct power_domain *power_domain);
Peng Fan58d3de12018-07-27 10:20:36 +0800162#else
163static inline int power_domain_off(struct power_domain *power_domain)
164{
165 return -ENOSYS;
166}
167#endif
Stephen Warren61f5ddc2016-07-13 13:45:31 -0600168
169#endif