]>
Commit | Line | Data |
---|---|---|
61f5ddcb SW |
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_free - Free a previously requested power domain. | |
95 | * | |
96 | * @power_domain: A power domain struct that was previously successfully | |
97 | * requested by power_domain_get(). | |
98 | * @return 0 if OK, or a negative error code. | |
99 | */ | |
100 | int power_domain_free(struct power_domain *power_domain); | |
101 | ||
102 | /** | |
103 | * power_domain_on - Enable power to a power domain. | |
104 | * | |
105 | * @power_domain: A power domain struct that was previously successfully | |
106 | * requested by power_domain_get(). | |
107 | * @return 0 if OK, or a negative error code. | |
108 | */ | |
109 | int power_domain_on(struct power_domain *power_domain); | |
110 | ||
111 | /** | |
112 | * power_domain_off - Disable power ot a power domain. | |
113 | * | |
114 | * @power_domain: A power domain struct that was previously successfully | |
115 | * requested by power_domain_get(). | |
116 | * @return 0 if OK, or a negative error code. | |
117 | */ | |
118 | int power_domain_off(struct power_domain *power_domain); | |
119 | ||
120 | #endif |