1 /** 2 ***************************************************************************************** 3 * 4 * @file gr55xx_pwr.h 5 * 6 * @brief GR55XX Platform Power Manager Module API 7 * 8 ***************************************************************************************** 9 * @attention 10 #####Copyright (c) 2019 GOODIX 11 All rights reserved. 12 13 Redistribution and use in source and binary forms, with or without 14 modification, are permitted provided that the following conditions are met: 15 * Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 * Redistributions in binary form must reproduce the above copyright 18 notice, this list of conditions and the following disclaimer in the 19 documentation and/or other materials provided with the distribution. 20 * Neither the name of GOODIX nor the names of its contributors may be used 21 to endorse or promote products derived from this software without 22 specific prior written permission. 23 24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE 28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 POSSIBILITY OF SUCH DAMAGE. 35 ***************************************************************************************** 36 */ 37 38 /** 39 * @addtogroup SYSTEM 40 * @{ 41 */ 42 43 /** 44 * @addtogroup PWR Power Manager 45 * @{ 46 * @brief Definitions and prototypes for the Power Manager interface. 47 */ 48 49 50 #ifndef __GR55XX_PWR_H_ 51 #define __GR55XX_PWR_H_ 52 53 #include <stdint.h> 54 #include <stdbool.h> 55 #include <stdio.h> 56 57 #include "system_gr55xx.h" 58 59 /** 60 * @defgroup GR55XX_PWR_TYPEDEF Typedefs 61 * @{ 62 */ 63 64 /** @brief power manager setting parameter. 65 * Use pwr_mgmt_var_set to transfer the parameters in the structure to PMU, 66 * and then the pwr_mgmt_mode_set function will use the new parameters for 67 * power management. 68 * Note that this is an advanced API, the wrong setting of parameters may 69 * lead to abnormal power management, so please use it carefully. 70 */ 71 typedef struct { 72 uint32_t pwr_mgmt_app_timer_thrd; /**< App timer threshold. */ 73 uint32_t pwr_mgmt_ble_core_thrd; /**< BLE timer threshold. */ 74 uint32_t pwr_mgmt_rtc_timer_thrd; /**< RTC timer threshold. */ 75 } pwr_mgmt_var_box_t; 76 77 /** @brief power manager boot type. */ 78 typedef enum { 79 COLD_BOOT = 0, /**< Cold boot state. */ 80 WARM_BOOT, /**< Warm boot state. */ 81 } boot_mode_t; 82 83 /** @brief power manager model. */ 84 typedef enum { 85 PMR_MGMT_ACTIVE_MODE = 0x0, /**< Full speed state. */ 86 PMR_MGMT_IDLE_MODE, /**< Idle state. */ 87 PMR_MGMT_SLEEP_MODE, /**< Deep sleep state. */ 88 } pwr_mgmt_mode_t; 89 90 /** @brief power manager device work state. */ 91 typedef enum { 92 DEVICE_BUSY = 0x0, /**< Device busy state. */ 93 DEVICE_IDLE, /**< Device idle state. */ 94 } pwr_mgmt_dev_state_t; 95 96 /** @brief power manager app timer work state. */ 97 typedef enum { 98 EVENT_APP_TIMER_START = 0, /**< App-timer start state. */ 99 EVENT_APP_TIMER_STOP, /**< App-timer stop state. */ 100 } notify_timer_event_t; 101 102 /** @brief PMU Tracking*/ 103 enum { 104 TRC_PWR_WFE_MODE = 0, /**< WFE mode. */ 105 TRC_PWR_DSLEEP_MODE, /**< Deep sleep mode. */ 106 TRC_PWR_ACTIVE_MODE, /**< Active mode. */ 107 TRC_PWR_BLE_RET_DSLEEP, /**< BLE return deep sleep. */ 108 TRC_PWR_APP_TIMER_REFUSE, /**< App timer refuse. */ 109 TRC_PWR_APP_TIMER_PASS, /**< App timer pass. */ 110 TRC_PWR_BLE_TIMER_PASS, /**< BLE timer pass. */ 111 }; 112 113 /** @brief parameter configuration table. */ 114 typedef struct { 115 uint16_t pwr_dur; /**< Duration. */ 116 uint16_t pwr_ext; /**< External wake-up. */ 117 uint16_t pwr_osc; /**< OSC. */ 118 uint8_t pwr_delay_hslot; /**< Delay half slot. */ 119 uint16_t pwr_delay_hus; /**< Delay half us. */ 120 uint16_t pwr_push_hus; /**< Push half us. */ 121 uint32_t pwr_timer_ths; /**< APP timer threshold. */ 122 uint32_t pwr_ble_ths; /**< BLE timer threshold. */ 123 } pwr_table_t; 124 125 /** @brief Trace function type. */ 126 typedef void (*trace_func_t)(uint8_t); 127 128 /** @brief Peripheral function type. */ 129 typedef void (*periph_func_t)(void); 130 131 /** @brief Before sleep function type. */ 132 typedef void (*pwr_before_sleep_func_t)(void); 133 134 /** @brief Device check function type. */ 135 typedef pwr_mgmt_dev_state_t (*pwr_dev_check_func_t)(void); 136 137 /** @brief function registered to dump io configuration. */ 138 typedef void (*io_dump_func_t)(void); 139 140 /** @brief mem check process type. */ 141 typedef void (*mem_check_proc_t)(void); 142 143 /** @brief pwr table. */ 144 #define MAX_PWR_TABLE_LEN 12 145 extern pwr_table_t pwr_table[MAX_PWR_TABLE_LEN]; 146 147 /** @} */ 148 149 /** @addtogroup GR55XX_PWR_FUNCTIONS Functions 150 * @{ */ 151 /** 152 ***************************************************************************************** 153 * @brief This function allows ARM to enter deep sleep mode, but users should not use this 154 * function directly. 155 * Note that this function is only available in environments where non-RTOS is used, 156 * and that users can only execute it while in main.c. 157 * @retval : pwr_mgmt_mode_t 158 ***************************************************************************************** 159 */ 160 pwr_mgmt_mode_t pwr_mgmt_shutdown(void); 161 162 /** 163 **************************************************************************************** 164 * @brief Get the current boot mode. 165 * @retval : cold boot or warm boot. 166 **************************************************************************************** 167 */ 168 boot_mode_t pwr_mgmt_get_wakeup_flag(void); 169 170 /** 171 **************************************************************************************** 172 * @brief Mark the mode of next boot, cold boot or warm boot. 173 * @param[in] boot_mode : cold boot or warm boot. 174 * @retval : void 175 **************************************************************************************** 176 */ 177 void pwr_mgmt_set_wakeup_flag(boot_mode_t boot_mode); 178 179 /** 180 **************************************************************************************** 181 * @brief Set the specified sleep mode. When the setting is completed, the system will 182 * automatically enter the specified sleep mode through the strategy. 183 * @param[in] pm_mode : sleep level 184 * @retval : void 185 **************************************************************************************** 186 */ 187 void pwr_mgmt_mode_set(pwr_mgmt_mode_t pm_mode); 188 189 /** 190 **************************************************************************************** 191 * @brief Get the specified sleep mode. 192 * @retval : pwr_mgmt_mode_t 193 **************************************************************************************** 194 */ 195 pwr_mgmt_mode_t pwr_mgmt_mode_get(void); 196 197 /** 198 **************************************************************************************** 199 * @brief Get the power state of baseband. 200 * @retval : pwr_mgmt_mode_t 201 **************************************************************************************** 202 */ 203 pwr_mgmt_mode_t pwr_mgmt_baseband_state_get(void); 204 205 /** 206 **************************************************************************************** 207 * @brief Get the state of extenal timer. 208 * @retval : pwr_mgmt_mode_t 209 **************************************************************************************** 210 */ 211 pwr_mgmt_mode_t pwr_mgmt_check_ext_timer(void); 212 213 /** 214 **************************************************************************************** 215 * @brief Sleep Policy Scheduling Function. 216 * Note that: 217 * 1. This function shall only be used in non-RTOS environments; 218 * 2. This function shall only be used in main function; 219 * 3. Local variables shall not be used in main function when this api used. 220 * @retval : void 221 **************************************************************************************** 222 */ 223 void pwr_mgmt_schedule(void); 224 225 /** 226 **************************************************************************************** 227 * @brief Wake the BLE core via an external request. 228 * @return status 229 * @retval The status of the requested operation. 230 * 231 * false, if the BLE core is not sleeping. 232 * true, if the BLE core was woken up successfully. 233 * 234 **************************************************************************************** 235 */ 236 bool pwr_mgmt_ble_wakeup(void); 237 238 239 /** 240 **************************************************************************************** 241 * @brief Check whether there are ble events in the queue, and if so, handle them immediately. 242 * @retval : void 243 **************************************************************************************** 244 */ 245 void pwr_mgmt_check_ble_event(void); 246 247 /** 248 **************************************************************************************** 249 * @brief This function is used to push startup information in app timer. 250 * This information will optimize power management strategy. 251 * Note that this function is an advanced API and users should not use it directly. 252 * @param[in] timer_event : EVENT_APP_TIMER_START or EVENT_APP_TIMER_STOP 253 * @retval : void 254 **************************************************************************************** 255 */ 256 void pwr_mgmt_notify_timer_event(notify_timer_event_t timer_event); 257 258 /** 259 **************************************************************************************** 260 * @brief Query the sleep mode that the current system can access. 261 * @retval : void 262 **************************************************************************************** 263 */ 264 pwr_mgmt_mode_t pwr_mgmt_get_sleep_mode(void); 265 266 /** 267 **************************************************************************************** 268 * @brief Update wakeup param. 269 * @retval : void 270 **************************************************************************************** 271 */ 272 void pwr_mgmt_update_wkup_param(void); 273 274 /** 275 **************************************************************************************** 276 * @brief Execution of this function allows ARM to enter the WFE state and exit the WFE 277 * state when an event or interrupt occurs. 278 * @retval : void 279 **************************************************************************************** 280 */ 281 void pwr_mgmt_wfe_sleep(void); 282 283 /** 284 **************************************************************************************** 285 * @brief Execution of this function allows ARM to enter the ultra sleep state and wakeup 286 * the chip when an event occurs. 287 * @param time_ms : Specifies the wake-up time during ultra sleep. If time_ms is equal to 0, 288 then sleep timer will not be enabled. 289 This parameter must be a number between min_value = 0 and max_value = 131071 290 * @retval : void 291 **************************************************************************************** 292 */ 293 void pwr_mgmt_ultra_sleep(uint32_t time_ms); 294 295 /** 296 **************************************************************************************** 297 * @brief PMU Initialization Function. 298 * @param p_pwr_table : PMU parameter configuration table. 299 * @param sys_clk : the clock of system 300 * @return void 301 **************************************************************************************** 302 */ 303 void pwr_mgmt_init(pwr_table_t *p_pwr_table, mcu_clock_type_t sys_clk); 304 305 /** 306 **************************************************************************************** 307 * @brief Peripheral Controller Initialization Register interface. 308 * @param p_periph_init : the pointer of device init function. 309 * @return void 310 **************************************************************************************** 311 */ 312 void pwr_mgmt_dev_init(periph_func_t p_periph_init); 313 314 /** 315 **************************************************************************************** 316 * @brief Device config resume interface. 317 * @return void 318 **************************************************************************************** 319 */ 320 void pwr_mgmt_dev_resume(void); 321 322 /** 323 **************************************************************************************** 324 * @brief Device config suspend interface. 325 * @return void 326 **************************************************************************************** 327 */ 328 pwr_mgmt_dev_state_t pwr_mgmt_dev_suspend(void); 329 330 /** 331 **************************************************************************************** 332 * @brief Mem state control under deep sleep & work state. 333 * @param mem_sleep_state : control in deep sleep. 334 * @param mem_work_state : control in work state. 335 * @return void 336 **************************************************************************************** 337 */ 338 void pwr_mgmt_mem_ctl_set(uint32_t mem_sleep_state, uint32_t mem_work_state); 339 340 /** 341 **************************************************************************************** 342 * @brief Set PMU callback function. 343 * @param dev_check_fun : Device check callback function. 344 * @param before_sleep_fun : Pre-execution callback function for deep sleep. 345 * @return void 346 **************************************************************************************** 347 */ 348 void pwr_mgmt_set_callback(pwr_dev_check_func_t dev_check_fun, pwr_before_sleep_func_t before_sleep_fun); 349 350 /** 351 **************************************************************************************** 352 * @brief Set the wakeup source. 353 * @param[in] wakeup_source : 354 * PWR_WKUP_COND_EXT 355 * PWR_WKUP_COND_TIMER 356 * PWR_WKUP_COND_BLE 357 * PWR_WKUP_COND_CALENDAR 358 * PWR_WKUP_COND_BOD_FEDGE 359 * PWR_WKUP_COND_MSIO_COMP 360 * @retval : void 361 **************************************************************************************** 362 */ 363 void pwr_mgmt_wakeup_source_setup(uint32_t wakeup_source); 364 365 /** 366 **************************************************************************************** 367 * @brief Clear the wakeup source. 368 * @param[in] wakeup_source : 369 * PWR_WKUP_COND_EXT 370 * PWR_WKUP_COND_TIMER 371 * PWR_WKUP_COND_BLE 372 * PWR_WKUP_COND_CALENDAR 373 * PWR_WKUP_COND_BOD_FEDGE 374 * PWR_WKUP_COND_MSIO_COMP 375 * @retval : void 376 **************************************************************************************** 377 */ 378 void pwr_mgmt_wakeup_source_clear(uint32_t wakeup_source); 379 380 /** 381 **************************************************************************************** 382 * @brief Save context function. 383 * @retval : void 384 **************************************************************************************** 385 */ 386 void pwr_mgmt_save_context(void); 387 388 /** 389 **************************************************************************************** 390 * @brief Load context function. 391 * @retval : void 392 **************************************************************************************** 393 */ 394 void pwr_mgmt_load_context(void); 395 396 /** 397 **************************************************************************************** 398 * @brief Disable nvic irq. 399 * @retval : void 400 **************************************************************************************** 401 */ 402 void pwr_mgmt_disable_nvic_irq(void); 403 404 /** 405 **************************************************************************************** 406 * @brief Enable nvic irq. 407 * @retval : void 408 **************************************************************************************** 409 */ 410 void pwr_mgmt_enable_nvic_irq(void); 411 412 /** 413 **************************************************************************************** 414 * @brief Check nvic irq. 415 * @retval : void 416 **************************************************************************************** 417 */ 418 bool pwr_mgmt_check_pend_irq(void); 419 420 /** 421 **************************************************************************************** 422 * @brief Trace function register. 423 * @param[in] trace_func: Trace function. 424 * @retval : void 425 **************************************************************************************** 426 */ 427 void pwr_mgmt_register_trace_func(trace_func_t trace_func); 428 429 /** 430 **************************************************************************************** 431 * @brief function registered to dump io configuration. 432 * @retval : void 433 **************************************************************************************** 434 */ 435 void pwr_mgmt_register_io_dump_func(io_dump_func_t dump_func); 436 437 /** @} */ 438 439 #endif 440 /** @} */ 441 /** @} */ 442