LXR uboot/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
  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 */
  90#if CONFIG_IS_ENABLED(POWER_DOMAIN)
  91int power_domain_get(struct udevice *dev, struct power_domain *power_domain);
  92#else
  93static inline
  94int power_domain_get(struct udevice *dev, struct power_domain *power_domain)
  95{
  96        return -ENOSYS;
  97}
  98#endif
  99
 100/**
 101 * 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/**
 122 * 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 */
 128#if CONFIG_IS_ENABLED(POWER_DOMAIN)
 129int power_domain_free(struct power_domain *power_domain);
 130#else
 131static inline int power_domain_free(struct power_domain *power_domain)
 132{
 133        return -ENOSYS;
 134}
 135#endif
 136
 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 */
 144#if CONFIG_IS_ENABLED(POWER_DOMAIN)
 145int power_domain_on(struct power_domain *power_domain);
 146#else
 147static inline int power_domain_on(struct power_domain *power_domain)
 148{
 149        return -ENOSYS;
 150}
 151#endif
 152
 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 */
 160#if CONFIG_IS_ENABLED(POWER_DOMAIN)
 161int power_domain_off(struct power_domain *power_domain);
 162#else
 163static inline int power_domain_off(struct power_domain *power_domain)
 164{
 165        return -ENOSYS;
 166}
 167#endif
 168
 169#endif
 170