1 /* 2 * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 #include <stdint.h> 9 #include <stdbool.h> 10 #include "sdkconfig.h" 11 #include "esp_err.h" 12 #include "esp_sleep.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /** 19 * @file sleep_modem.h 20 * 21 * This file contains declarations of MAC and baseband power consumption related functions in light sleep mode. 22 */ 23 24 #if CONFIG_MAC_BB_PD 25 26 /** 27 * @brief A callback function completes MAC and baseband power down operation 28 * 29 * In light sleep mode, execute Wi-Fi and Bluetooth module MAC and baseband 30 * power down and backup register configuration information operations. 31 */ 32 void mac_bb_power_down_cb_execute(void); 33 34 /** 35 * @brief A callback function completes MAC and baseband power up operation 36 * 37 * In light sleep mode, execute Wi-Fi and Bluetooth module MAC and baseband 38 * power up and restore register configuration information operations. 39 */ 40 void mac_bb_power_up_cb_execute(void); 41 42 #endif // CONFIG_MAC_BB_PD 43 44 #if SOC_PM_RETENTION_HAS_CLOCK_BUG && CONFIG_MAC_BB_PD 45 /** 46 * @brief Register sleep prepare callback for Bluetooth/IEEE802154 MAC and baseband 47 * 48 * @param pd_cb function to call when power down 49 * @param pu_cb function to call when power up 50 */ 51 void sleep_modem_register_mac_bb_module_prepare_callback(mac_bb_power_down_cb_t pd_cb, 52 mac_bb_power_up_cb_t pu_cb); 53 54 /** 55 * @brief Unregister sleep prepare callback for Bluetooth/IEEE802154 MAC and baseband 56 * 57 * @param pd_cb function to call when power down 58 * @param pu_cb function to call when power up 59 */ 60 void sleep_modem_unregister_mac_bb_module_prepare_callback(mac_bb_power_down_cb_t pd_cb, 61 mac_bb_power_up_cb_t pu_cb); 62 63 /** 64 * @brief MAC and baseband power up operation 65 * 66 * In light sleep mode, execute IEEE802154/Bluetooth module MAC and baseband 67 * power down and backup prepare operations. 68 */ 69 void sleep_modem_mac_bb_power_down_prepare(void); 70 71 /** 72 * @brief MAC and baseband power up operation 73 * 74 * In light sleep mode, execute IEEE802154/Bluetooth module MAC and baseband 75 * power up and restore prepare operations. 76 */ 77 void sleep_modem_mac_bb_power_up_prepare(void); 78 #endif // SOC_PM_RETENTION_HAS_CLOCK_BUG && CONFIG_MAC_BB_PD 79 80 #if SOC_PM_SUPPORT_PMU_MODEM_STATE 81 82 /** 83 * @brief The retention action in the modem state of WiFi PHY module 84 * 85 * @param restore true for restore the PHY context, false for backup the PHY context 86 */ 87 void sleep_modem_wifi_do_phy_retention(bool restore); 88 89 /** 90 * @brief Get WiFi modem state 91 * 92 * @return true or false for WiFi modem state is enabled or disabled 93 */ 94 bool sleep_modem_wifi_modem_state_enabled(void); 95 96 /** 97 * @brief Get WiFi modem link done state 98 * 99 * @return true or false for WiFi modem link can be used to enable RF by REGDMA or can not be used 100 */ 101 bool sleep_modem_wifi_modem_link_done(void); 102 103 #endif /* SOC_PM_SUPPORT_PMU_MODEM_STATE */ 104 105 /** 106 * @brief Whether the current target allows Modem or the TOP power domain to be powered off during light sleep 107 * 108 * During light sleep on some targets, it is possible to power OFF the Modem or TOP 109 * power domains in order to further lower power power consumption. However, this 110 * can only occur on targets that support REGDMA for modem (WiFi, Bluetooth, 111 * IEEE802.15.4) retention. 112 */ 113 bool modem_domain_pd_allowed(void); 114 115 /** 116 * @brief Get the reject trigger signal of Modem system 117 * 118 * @return the reject trigger signal of Modem system. 119 */ 120 uint32_t sleep_modem_reject_triggers(void); 121 122 /** 123 * @brief Configure the parameters of the modem subsytem during the sleep process 124 * 125 * In light sleep mode, the wake-up early time of the WiFi module and the TBTT 126 * interrupt early time (trigger enabling RF) are determined by the maximum and 127 * minimum frequency of system (higher system frequency means less time to wake 128 * up and enable RF). 129 * For the esp32c6 SOC, the modem state is strongly dependent on the light sleep 130 * mode, and the modem state will be enabled only when light sleep is enabled 131 * and the `CONFIG_ESP_WIFI_ENHANCED_LIGHT_SLEEP` is configured in menuconfig. 132 * 133 * @param max_freq_mhz the maximum frequency of system 134 * @param min_freq_mhz the minimum frequency of system 135 * @param light_sleep_enable ture or false for enable or disable light sleep mode, respectively 136 * 137 * @return 138 * - ESP_OK on success 139 */ 140 esp_err_t sleep_modem_configure(int max_freq_mhz, int min_freq_mhz, bool light_sleep_enable); 141 142 /** 143 * @brief Callback function type for peripherals to know light sleep wakeup overhead. 144 * 145 */ 146 typedef void (* inform_out_light_sleep_overhead_cb_t)(uint32_t); 147 148 /** 149 * @brief Register informing peripherals light sleep wakeup overhead time callback 150 * 151 * This function allows you to register a callback that informs the peripherals of 152 * the wakeup overhead time of light sleep. 153 * @param cb function to inform time 154 * @return 155 * - ESP_OK on success 156 * - ESP_ERR_NO_MEM if no more callback slots are available 157 */ 158 esp_err_t esp_pm_register_inform_out_light_sleep_overhead_callback(inform_out_light_sleep_overhead_cb_t cb); 159 160 /** 161 * @brief Unregister informing peripherals light sleep wakeup overhead time callback 162 * 163 * This function allows you to unregister a callback that informs the peripherals of 164 * the wakeup overhead time of light sleep. 165 * @param cb function to inform time 166 * @return 167 * - ESP_OK on success 168 * - ESP_ERR_INVALID_STATE if the given callback hasn't been registered before 169 */ 170 esp_err_t esp_pm_unregister_inform_out_light_sleep_overhead_callback(inform_out_light_sleep_overhead_cb_t cb); 171 172 /** 173 * @brief A callback that informs the peripherals of the wakeup overhead time of light sleep 174 * 175 * @param out_light_sleep_time wakeup overhead time of light sleep 176 */ 177 void periph_inform_out_light_sleep_overhead(uint32_t out_light_sleep_time); 178 179 /** 180 * @brief Callback function type for peripherals to know light sleep default parameters 181 */ 182 typedef void (* update_light_sleep_default_params_config_cb_t)(int, int); 183 184 /** 185 * @brief Register peripherals light sleep default parameters configure callback 186 * 187 * This function allows you to register a callback that configure the peripherals 188 * of default parameters of light sleep 189 * @param cb function to update default parameters 190 */ 191 void esp_pm_register_light_sleep_default_params_config_callback(update_light_sleep_default_params_config_cb_t cb); 192 193 /** 194 * @brief Unregister peripherals light sleep default parameters configure Callback 195 * 196 * This function allows you to unregister a callback that configure the peripherals 197 * of default parameters of light sleep 198 */ 199 void esp_pm_unregister_light_sleep_default_params_config_callback(void); 200 201 #if SOC_PM_SUPPORT_PMU_MODEM_STATE 202 /** 203 * @brief Init Wi-Fi modem state. 204 * 205 * This function init wifi modem state. 206 * @return 207 * - ESP_OK on success 208 * - ESP_ERR_NO_MEM if no memory for link 209 */ 210 esp_err_t sleep_modem_wifi_modem_state_init(void); 211 212 /** 213 * @brief Deinit Wi-Fi modem state. 214 * 215 * This function deinit wifi modem state. 216 */ 217 void sleep_modem_wifi_modem_state_deinit(void); 218 219 /** 220 * @brief Function to check Wi-Fi modem state to skip light sleep. 221 * 222 * This function is to check if light sleep should skip by Wi-Fi modem state . 223 * @return 224 * - true skip light sleep 225 * - false not skip light sleep 226 */ 227 bool sleep_modem_wifi_modem_state_skip_light_sleep(void); 228 #endif 229 230 #ifdef __cplusplus 231 } 232 #endif 233
