1 /* 2 * Copyright (c) 2025-2026 Texas Instruments Incorporated - https://www.ti.com 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /* 8 * Device Power Management API 9 * 10 * This header provides device power management operations including device 11 * enable/disable, reset isolation, retention control, context loss tracking, 12 * and SoC-specific device initialization and state management functions. 13 */ 14 15 #ifndef TI_DEVICE_PM_H 16 #define TI_DEVICE_PM_H 17 18 #include <stdbool.h> 19 20 /** 21 * ti_soc_device_get_state() - Get the current device state (SoC specific impl.) 22 * @dev: The device to query. 23 * 24 * Return: Non-zero if the device is enabled, zero if disabled. 25 */ 26 uint32_t ti_soc_device_get_state(struct ti_device *dev); 27 28 /** 29 * ti_soc_device_set_reset_iso() - Set the reset isolation flag for a device (SoC specific impl.) 30 * @dev: The device to modify. 31 * @enable: True to enable reset isolation, false to disable. 32 */ 33 void ti_soc_device_set_reset_iso(struct ti_device *dev, bool enable); 34 35 /** 36 * ti_soc_device_get_context_loss_count() - Get context loss count 37 * @device: The device to query. 38 * 39 * Return: The current loss count of the device. 40 */ 41 uint32_t ti_soc_device_get_context_loss_count(struct ti_device *dev); 42 43 /** 44 * ti_soc_device_enable() - Enable a device (SoC specific impl.) 45 * @device: The device to modify. 46 */ 47 void ti_soc_device_enable(struct ti_device *dev); 48 49 /** 50 * ti_soc_device_disable() - Disable a device (SoC specific impl.) 51 * @device: The device to modify. 52 * @domain_reset: True if the device is being disabled due to a domain reset. 53 */ 54 void ti_soc_device_disable(struct ti_device *dev, bool domain_reset); 55 56 /** 57 * ti_soc_device_clear_flags() - Clear a device initialization flags 58 * @dev: The device to modify. 59 */ 60 void ti_soc_device_clear_flags(struct ti_device *dev); 61 62 /** 63 * ti_soc_device_ret_enable() - Enable retention on a device (SoC specific impl.) 64 * @device: The device to modify. 65 */ 66 void ti_soc_device_ret_enable(struct ti_device *dev); 67 68 /** 69 * ti_soc_device_ret_disable() - Disable retention on a device (SoC specific impl.) 70 * @device: The device to modify. 71 */ 72 void ti_soc_device_ret_disable(struct ti_device *dev); 73 74 /** 75 * ti_soc_device_init() - Perform SoC level initialization of a device. 76 * 77 * The device to init. 78 * 79 * Return: 0 on success, -EAGAIN if device is not yet ready to be initialized. 80 */ 81 int32_t ti_soc_device_init(struct ti_device *dev); 82 83 /** 84 * ti_soc_device_init_complete() - Notify SoC device impl. that device init is complete. 85 * 86 * This allows the SoC implementation to drop any extra references it's been 87 * holding during init. 88 */ 89 void ti_soc_device_init_complete(void); 90 91 /** 92 * ti_device_disable() - Disables a device. 93 * @device: The device to modify. 94 * @domain_reset: True if the device is being disabled due to a domain reset. 95 * 96 * Performs the steps necessary to disable a device. 97 */ 98 void ti_device_disable(struct ti_device *dev, bool domain_reset); 99 100 /** 101 * ti_device_set_state() - Enable/disable a device. 102 * @device: The device to modify. 103 * @host_idx: The index of the host making the request. 104 * @enable: True to enable the device, false to allow the PMMC to power down the device. 105 * 106 * This indicates the desired state of a device by the HLOS. If a device is 107 * enabled, the PMMC will make sure the device and its dependencies are 108 * ready. If the device is not enabled, the PMMC will opportunistically 109 * utilize power management modes of that device and its dependencies. 110 * 111 * Enabling a device (if disabled) increments the device's reference count. 112 * Disabling a device (if enabled) decrements the devices' reference count. 113 */ 114 void ti_device_set_state(struct ti_device *dev, uint8_t host_idx, bool enable); 115 116 /** 117 * ti_device_set_retention() - Enable/disable retention on a device. 118 * @device: The device to modify. 119 * @retention: True to enable retention, false to disable it. 120 * 121 * When a device is in retention, but disabled, the PMMC can still perform 122 * power management tasks, but the device must keep its context. Enabling 123 * retention is a way save power, but still be able to bring the device back 124 * to full functionality quickly. 125 */ 126 void ti_device_set_retention(struct ti_device *dev, bool retention); 127 128 /** 129 * ti_device_clear_flags() - Clear a device initialization flags 130 * @dev: The device to modify. 131 */ 132 void ti_device_clear_flags(struct ti_device *dev); 133 134 /** 135 * ti_device_set_reset_iso() - Set the reset isolation flag for a device. 136 * @device: The device to modify. 137 * @enable: True to enable reset isolation, false to disable. 138 * 139 * The effect of reset isolation is device and SoC specific, but it generally 140 * prevents the device from undergoing reset with the rest of the SoC. 141 */ 142 static inline void ti_device_set_reset_iso(struct ti_device *dev, bool enable) 143 { 144 ti_soc_device_set_reset_iso(dev, enable); 145 } 146 147 /* Return values for ti_device_get_state() and ti_soc_device_get_state() */ 148 #define TI_DEVICE_STATE_DISABLED 0U /* Module is off (SwRstDisable) */ 149 #define TI_DEVICE_STATE_ENABLED 1U /* Module is enabled or in retention */ 150 #define TI_DEVICE_STATE_TRANSITIONING 2U /* Module is transitioning or domains mixed */ 151 152 /** 153 * ti_device_get_state() - Get the current device state. 154 * @device: The device to query. 155 * 156 * Returns the current device state as configured by ti_device_set_state. 157 * 158 * Return: TI_DEVICE_STATE_DISABLED, TI_DEVICE_STATE_ENABLED, or 159 * TI_DEVICE_STATE_TRANSITIONING. 160 */ 161 static inline uint32_t ti_device_get_state(struct ti_device *dev) 162 { 163 return ti_soc_device_get_state(dev); 164 } 165 166 #endif /* TI_DEVICE_PM_H */ 167