include/power-domain.h

   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