1*4882a593Smuzhiyun /* 2*4882a593Smuzhiyun * Copyright (c) 2016, NVIDIA CORPORATION. 3*4882a593Smuzhiyun * 4*4882a593Smuzhiyun * SPDX-License-Identifier: GPL-2.0 5*4882a593Smuzhiyun */ 6*4882a593Smuzhiyun 7*4882a593Smuzhiyun #ifndef _POWER_DOMAIN_H 8*4882a593Smuzhiyun #define _POWER_DOMAIN_H 9*4882a593Smuzhiyun 10*4882a593Smuzhiyun /** 11*4882a593Smuzhiyun * A power domain is a portion of an SoC or chip that is powered by a 12*4882a593Smuzhiyun * switchable source of power. In many cases, software has control over the 13*4882a593Smuzhiyun * power domain, and can turn the power source on or off. This is typically 14*4882a593Smuzhiyun * done to save power by powering off unused devices, or to enable software 15*4882a593Smuzhiyun * sequencing of initial powerup at boot. This API provides a means for 16*4882a593Smuzhiyun * drivers to turn power domains on and off. 17*4882a593Smuzhiyun * 18*4882a593Smuzhiyun * A driver that implements UCLASS_POWER_DOMAIN is a power domain controller or 19*4882a593Smuzhiyun * provider. A controller will often implement multiple separate power domains, 20*4882a593Smuzhiyun * since the hardware it manages often has this capability. 21*4882a593Smuzhiyun * power-domain-uclass.h describes the interface which power domain controllers 22*4882a593Smuzhiyun * must implement. 23*4882a593Smuzhiyun * 24*4882a593Smuzhiyun * Depending on the power domain controller hardware, changing the state of a 25*4882a593Smuzhiyun * power domain may require performing related operations on other resources. 26*4882a593Smuzhiyun * For example, some power domains may require certain clocks to be enabled 27*4882a593Smuzhiyun * whenever the power domain is powered on, or during the time when the power 28*4882a593Smuzhiyun * domain is transitioning state. These details are implementation-specific 29*4882a593Smuzhiyun * and should ideally be encapsulated entirely within the provider driver, or 30*4882a593Smuzhiyun * configured through mechanisms (e.g. device tree) that do not require client 31*4882a593Smuzhiyun * drivers to provide extra configuration information. 32*4882a593Smuzhiyun * 33*4882a593Smuzhiyun * Power domain consumers/clients are the drivers for HW modules within the 34*4882a593Smuzhiyun * power domain. This header file describes the API used by those drivers. 35*4882a593Smuzhiyun * 36*4882a593Smuzhiyun * In many cases, a single complex IO controller (e.g. a PCIe controller) will 37*4882a593Smuzhiyun * be the sole logic contained within a power domain. In such cases, it is 38*4882a593Smuzhiyun * logical for the relevant device driver to directly control that power 39*4882a593Smuzhiyun * domain. In other cases, multiple controllers, each with their own driver, 40*4882a593Smuzhiyun * may be contained in a single power domain. Any logic require to co-ordinate 41*4882a593Smuzhiyun * between drivers for these multiple controllers is beyond the scope of this 42*4882a593Smuzhiyun * API at present. Equally, this API does not define or implement any policy 43*4882a593Smuzhiyun * by which power domains are managed. 44*4882a593Smuzhiyun */ 45*4882a593Smuzhiyun 46*4882a593Smuzhiyun struct udevice; 47*4882a593Smuzhiyun 48*4882a593Smuzhiyun /** 49*4882a593Smuzhiyun * struct power_domain - A handle to (allowing control of) a single power domain. 50*4882a593Smuzhiyun * 51*4882a593Smuzhiyun * Clients provide storage for power domain handles. The content of the 52*4882a593Smuzhiyun * structure is managed solely by the power domain API and power domain 53*4882a593Smuzhiyun * drivers. A power domain struct is initialized by "get"ing the power domain 54*4882a593Smuzhiyun * struct. The power domain struct is passed to all other power domain APIs to 55*4882a593Smuzhiyun * identify which power domain to operate upon. 56*4882a593Smuzhiyun * 57*4882a593Smuzhiyun * @dev: The device which implements the power domain. 58*4882a593Smuzhiyun * @id: The power domain ID within the provider. 59*4882a593Smuzhiyun * 60*4882a593Smuzhiyun * Currently, the power domain API assumes that a single integer ID is enough 61*4882a593Smuzhiyun * to identify and configure any power domain for any power domain provider. If 62*4882a593Smuzhiyun * this assumption becomes invalid in the future, the struct could be expanded 63*4882a593Smuzhiyun * to either (a) add more fields to allow power domain providers to store 64*4882a593Smuzhiyun * additional information, or (b) replace the id field with an opaque pointer, 65*4882a593Smuzhiyun * which the provider would dynamically allocate during its .of_xlate op, and 66*4882a593Smuzhiyun * process during is .request op. This may require the addition of an extra op 67*4882a593Smuzhiyun * to clean up the allocation. 68*4882a593Smuzhiyun */ 69*4882a593Smuzhiyun struct power_domain { 70*4882a593Smuzhiyun struct udevice *dev; 71*4882a593Smuzhiyun /* 72*4882a593Smuzhiyun * Written by of_xlate. We assume a single id is enough for now. In the 73*4882a593Smuzhiyun * future, we might add more fields here. 74*4882a593Smuzhiyun */ 75*4882a593Smuzhiyun unsigned long id; 76*4882a593Smuzhiyun }; 77*4882a593Smuzhiyun 78*4882a593Smuzhiyun /** 79*4882a593Smuzhiyun * power_domain_get - Get/request the power domain for a device. 80*4882a593Smuzhiyun * 81*4882a593Smuzhiyun * This looks up and requests a power domain. Each device is assumed to have 82*4882a593Smuzhiyun * a single (or, at least one) power domain associated with it somehow, and 83*4882a593Smuzhiyun * that domain, or the first/default domain. The mapping of client device to 84*4882a593Smuzhiyun * provider power domain may be via device-tree properties, board-provided 85*4882a593Smuzhiyun * mapping tables, or some other mechanism. 86*4882a593Smuzhiyun * 87*4882a593Smuzhiyun * @dev: The client device. 88*4882a593Smuzhiyun * @power_domain A pointer to a power domain struct to initialize. 89*4882a593Smuzhiyun * @return 0 if OK, or a negative error code. 90*4882a593Smuzhiyun */ 91*4882a593Smuzhiyun int power_domain_get(struct udevice *dev, struct power_domain *power_domain); 92*4882a593Smuzhiyun 93*4882a593Smuzhiyun /** 94*4882a593Smuzhiyun * power_domain_free - Free a previously requested power domain. 95*4882a593Smuzhiyun * 96*4882a593Smuzhiyun * @power_domain: A power domain struct that was previously successfully 97*4882a593Smuzhiyun * requested by power_domain_get(). 98*4882a593Smuzhiyun * @return 0 if OK, or a negative error code. 99*4882a593Smuzhiyun */ 100*4882a593Smuzhiyun int power_domain_free(struct power_domain *power_domain); 101*4882a593Smuzhiyun 102*4882a593Smuzhiyun /** 103*4882a593Smuzhiyun * power_domain_on - Enable power to a power domain. 104*4882a593Smuzhiyun * 105*4882a593Smuzhiyun * @power_domain: A power domain struct that was previously successfully 106*4882a593Smuzhiyun * requested by power_domain_get(). 107*4882a593Smuzhiyun * @return 0 if OK, or a negative error code. 108*4882a593Smuzhiyun */ 109*4882a593Smuzhiyun int power_domain_on(struct power_domain *power_domain); 110*4882a593Smuzhiyun 111*4882a593Smuzhiyun /** 112*4882a593Smuzhiyun * power_domain_off - Disable power ot a power domain. 113*4882a593Smuzhiyun * 114*4882a593Smuzhiyun * @power_domain: A power domain struct that was previously successfully 115*4882a593Smuzhiyun * requested by power_domain_get(). 116*4882a593Smuzhiyun * @return 0 if OK, or a negative error code. 117*4882a593Smuzhiyun */ 118*4882a593Smuzhiyun int power_domain_off(struct power_domain *power_domain); 119*4882a593Smuzhiyun 120*4882a593Smuzhiyun #endif 121