include/power-domain.h

   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
  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
 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
 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
 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
 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
 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
 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
 205 static inline int dev_power_domain_off(struct udevice *dev)
 206 {
 207         return 0;
 208 }
 209 #endif
 210
 211 #endif