| Stephen Warren | 61f5ddc | 2016-07-13 13:45:31 -0600 | [diff] [blame] | 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 |