Goodix
GR551x API Reference  V1_6_06_B5676
gr55xx_pwr.h
Go to the documentation of this file.
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 {
73  uint32_t pwr_mgmt_app_timer_thrd; /**< App timer threshold. */
74  uint32_t pwr_mgmt_ble_core_thrd; /**< BLE timer threshold. */
75  uint32_t pwr_mgmt_rtc_timer_thrd; /**< RTC timer threshold. */
77 
78 /**@brief power manager boot type. */
79 typedef enum
80 {
81  COLD_BOOT = 0, /**< Cold boot state. */
82  WARM_BOOT, /**< Warm boot state. */
83 } boot_mode_t;
84 
85 /**@brief power manager model. */
86 typedef enum
87 {
88  PMR_MGMT_ACTIVE_MODE = 0x0, /**< Full speed state. */
89  PMR_MGMT_IDLE_MODE, /**< Idle state. */
90  PMR_MGMT_SLEEP_MODE, /**< Deep sleep state. */
92 
93 /**@brief power manager device work state. */
94 typedef enum
95 {
96  DEVICE_BUSY = 0x0, /**< Device busy state. */
97  DEVICE_IDLE, /**< Device idle state. */
99 
100 /**@brief power manager app timer work state. */
101 typedef enum
102 {
103  EVENT_APP_TIMER_START = 0, /**< App-timer start state. */
104  EVENT_APP_TIMER_STOP, /**< App-timer stop state. */
106 
107 /**@brief PMU Tracking*/
108 enum
109 {
110  TRC_PWR_WFE_MODE = 0, /**< WFE mode. */
111  TRC_PWR_DSLEEP_MODE, /**< Deep sleep mode. */
112  TRC_PWR_ACTIVE_MODE, /**< Active mode. */
113  TRC_PWR_BLE_RET_DSLEEP, /**< BLE return deep sleep. */
114  TRC_PWR_APP_TIMER_REFUSE, /**< App timer refuse. */
115  TRC_PWR_APP_TIMER_PASS, /**< App timer pass. */
116  TRC_PWR_BLE_TIMER_PASS, /**< BLE timer pass. */
117 };
118 
119 /**@brief parameter configuration table. */
120 typedef struct
121 {
122  uint16_t pwr_dur; /**< Duration. */
123  uint16_t pwr_ext; /**< External wake-up. */
124  uint16_t pwr_osc; /**< OSC. */
125  uint8_t pwr_delay_hslot; /**< Delay half slot. */
126  uint16_t pwr_delay_hus; /**< Delay half us. */
127  uint16_t pwr_push_hus; /**< Push half us. */
128  uint32_t pwr_timer_ths; /**< APP timer threshold. */
129  uint32_t pwr_ble_ths; /**< BLE timer threshold. */
130 } pwr_table_t;
131 
132 /**@brief Trace function type. */
133 typedef void (*trace_func_t)(uint8_t);
134 
135 /**@brief Peripheral function type. */
136 typedef void (*periph_func_t)(void);
137 
138 /**@brief Before sleep function type. */
139 typedef void (*pwr_before_sleep_func_t)(void);
140 
141 /**@brief Device check function type. */
143 
144 /**@brief function registered to dump io configuration. */
145 typedef void (*io_dump_func_t)(void);
146 
147 /**@brief pwr table. */
148 extern pwr_table_t pwr_table[];
149 
150 /** @} */
151 
152 /** @addtogroup GR55XX_PWR_FUNCTIONS Functions
153  * @{ */
154 /**
155  *****************************************************************************************
156  * @brief This function allows ARM to enter deep sleep mode, but users should not use this
157  * function directly.
158  * Note that this function is only available in environments where non-RTOS is used,
159  * and that users can only execute it while in main.c.
160  * @retval : pwr_mgmt_mode_t
161  *****************************************************************************************
162  */
164 
165 /**
166  ****************************************************************************************
167  * @brief Get the current boot mode.
168  * @retval : cold boot or warm boot.
169  ****************************************************************************************
170  */
172 
173 /**
174  ****************************************************************************************
175  * @brief Mark the mode of next boot, cold boot or warm boot.
176  * @param[in] boot_mode : cold boot or warm boot.
177  * @retval : void
178  ****************************************************************************************
179  */
181 
182 /**
183  ****************************************************************************************
184  * @brief Set the specified sleep mode. When the setting is completed, the system will
185  * automatically enter the specified sleep mode through the strategy.
186  * @param[in] pm_mode : sleep level
187  * @retval : void
188  ****************************************************************************************
189  */
191 
192 /**
193  ****************************************************************************************
194  * @brief Get the specified sleep mode.
195  * @retval : pwr_mgmt_mode_t
196  ****************************************************************************************
197  */
199 
200 /**
201  ****************************************************************************************
202  * @brief Get the power state of baseband.
203  * @retval : pwr_mgmt_mode_t
204  ****************************************************************************************
205  */
207 
208 /**
209  ****************************************************************************************
210  * @brief Get the state of extenal timer.
211  * @retval : pwr_mgmt_mode_t
212  ****************************************************************************************
213  */
215 
216 
217 
218 /**
219  ****************************************************************************************
220  * @brief Sleep Policy Scheduling Function.
221  * Note that:
222  * 1. This function shall only be used in non-RTOS environments;
223  * 2. This function shall only be used in main function;
224  * 3. Local variables shall not be used in main function when this api used.
225  * @retval : void
226  ****************************************************************************************
227  */
228 void pwr_mgmt_schedule(void);
229 
230 /**
231  ****************************************************************************************
232  * @brief Wake the BLE core via an external request.
233  * @return status
234  * @retval The status of the requested operation.
235  *
236  * false, if the BLE core is not sleeping.
237  * true, if the BLE core was woken up successfully.
238  *
239  ****************************************************************************************
240  */
242 
243 
244 /**
245  ****************************************************************************************
246  * @brief Check whether there are ble events in the queue, and if so, handle them immediately.
247  * @retval : void
248  ****************************************************************************************
249  */
251 
252 
253 /**
254  ****************************************************************************************
255  * @brief This function is used to push startup information in app timer.
256  * This information will optimize power management strategy.
257  * Note that this function is an advanced API and users should not use it directly.
258  * @param[in] timer_event : EVENT_APP_TIMER_START or EVENT_APP_TIMER_STOP
259  * @retval : void
260  ****************************************************************************************
261  */
263 
264 /**
265  ****************************************************************************************
266  * @brief Query the sleep mode that the current system can access.
267  * @retval : void
268  ****************************************************************************************
269  */
271 
272 
273 /**
274  ****************************************************************************************
275  * @brief Update wakeup param.
276  * @retval : void
277  ****************************************************************************************
278  */
280 
281 /**
282  ****************************************************************************************
283  * @brief Execution of this function allows ARM to enter the WFE state and exit the WFE
284  * state when an event or interrupt occurs.
285  * @retval : void
286  ****************************************************************************************
287  */
289 
290 /**
291  ****************************************************************************************
292  * @brief Execution of this function allows ARM to enter the ultra sleep state and wakeup
293  * the chip when an event occurs.
294  * @param time_ms : Specifies the wake-up time during ultra sleep. If time_ms is equal to 0,
295  then sleep timer will not be enabled.
296  This parameter must be a number between min_value = 0 and max_value = 131071
297  * @retval : void
298  ****************************************************************************************
299  */
300 void pwr_mgmt_ultra_sleep(uint32_t time_ms);
301 
302 /**
303  ****************************************************************************************
304  * @brief PMU Initialization Function.
305  * @param p_pwr_table : PMU parameter configuration table.
306  * @param sys_clk : the clock of system
307  * @return void
308  ****************************************************************************************
309  */
310 void pwr_mgmt_init( pwr_table_t *p_pwr_table, mcu_clock_type_t sys_clk);
311 
312 /**
313  ****************************************************************************************
314  * @brief Peripheral Controller Initialization Register interface.
315  * @param p_periph_init : the pointer of device init function.
316  * @return void
317  ****************************************************************************************
318  */
319 void pwr_mgmt_dev_init(periph_func_t p_periph_init);
320 
321 /**
322  ****************************************************************************************
323  * @brief Device config resume interface.
324  * @return void
325  ****************************************************************************************
326  */
328 
329 /**
330  ****************************************************************************************
331  * @brief Device config suspend interface.
332  * @return void
333  ****************************************************************************************
334  */
336 
337 /**
338  ****************************************************************************************
339  * @brief Mem state control under deep sleep & work state.
340  * @param mem_sleep_state : control in deep sleep.
341  * @param mem_work_state : control in work state.
342  * @return void
343  ****************************************************************************************
344  */
345 void pwr_mgmt_mem_ctl_set(uint32_t mem_sleep_state, uint32_t mem_work_state);
346 
347 /**
348  ****************************************************************************************
349  * @brief Set PMU callback function.
350  * @param dev_check_fun : Device check callback function.
351  * @param before_sleep_fun : Pre-execution callback function for deep sleep.
352  * @return void
353  ****************************************************************************************
354  */
356 
357  /**
358  ****************************************************************************************
359  * @brief Set the wakeup source.
360  * @param[in] wakeup_source :
361  * PWR_WKUP_COND_EXT
362  * PWR_WKUP_COND_TIMER
363  * PWR_WKUP_COND_BLE
364  * PWR_WKUP_COND_CALENDAR
365  * PWR_WKUP_COND_BOD_FEDGE
366  * PWR_WKUP_COND_MSIO_COMP
367  * @retval : void
368  ****************************************************************************************
369  */
370 void pwr_mgmt_wakeup_source_setup(uint32_t wakeup_source);
371 
372  /**
373  ****************************************************************************************
374  * @brief Clear the wakeup source.
375  * @param[in] wakeup_source :
376  * PWR_WKUP_COND_EXT
377  * PWR_WKUP_COND_TIMER
378  * PWR_WKUP_COND_BLE
379  * PWR_WKUP_COND_CALENDAR
380  * PWR_WKUP_COND_BOD_FEDGE
381  * PWR_WKUP_COND_MSIO_COMP
382  * @retval : void
383  ****************************************************************************************
384  */
385 void pwr_mgmt_wakeup_source_clear(uint32_t wakeup_source);
386 
387  /**
388  ****************************************************************************************
389  * @brief Save context function.
390  * @retval : void
391  ****************************************************************************************
392  */
394 
395  /**
396  ****************************************************************************************
397  * @brief Load context function.
398  * @retval : void
399  ****************************************************************************************
400  */
402 
403  /**
404  ****************************************************************************************
405  * @brief Disable nvic irq.
406  * @retval : void
407  ****************************************************************************************
408  */
410 
411 /**
412  ****************************************************************************************
413  * @brief Enable nvic irq.
414  * @retval : void
415  ****************************************************************************************
416  */
418 
419 /**
420  ****************************************************************************************
421  * @brief Check nvic irq.
422  * @retval : void
423  ****************************************************************************************
424  */
426 
427 /**
428  ****************************************************************************************
429  * @brief Trace function register.
430  * @param[in] trace_func: Trace function.
431  * @retval : void
432  ****************************************************************************************
433  */
435 
436 /**
437  ****************************************************************************************
438  * @brief function registered to dump io configuration.
439  * @retval :
440  ****************************************************************************************
441  */
443 
444 /** @} */
445 
446 #endif
447 /** @} */
448 /** @} */
pwr_mgmt_ble_wakeup
bool pwr_mgmt_ble_wakeup(void)
Wake the BLE core via an external request.
io_dump_func_t
void(* io_dump_func_t)(void)
function registered to dump io configuration.
Definition: gr55xx_pwr.h:145
pwr_table_t::pwr_osc
uint16_t pwr_osc
OSC.
Definition: gr55xx_pwr.h:124
TRC_PWR_BLE_RET_DSLEEP
@ TRC_PWR_BLE_RET_DSLEEP
BLE return deep sleep.
Definition: gr55xx_pwr.h:113
pwr_table_t::pwr_ble_ths
uint32_t pwr_ble_ths
BLE timer threshold.
Definition: gr55xx_pwr.h:129
pwr_mgmt_get_sleep_mode
pwr_mgmt_mode_t pwr_mgmt_get_sleep_mode(void)
Query the sleep mode that the current system can access.
pwr_mgmt_init
void pwr_mgmt_init(pwr_table_t *p_pwr_table, mcu_clock_type_t sys_clk)
PMU Initialization Function.
pwr_mgmt_baseband_state_get
pwr_mgmt_mode_t pwr_mgmt_baseband_state_get(void)
Get the power state of baseband.
pwr_mgmt_mode_t
pwr_mgmt_mode_t
power manager model.
Definition: gr55xx_pwr.h:87
pwr_mgmt_mode_set
void pwr_mgmt_mode_set(pwr_mgmt_mode_t pm_mode)
Set the specified sleep mode.
pwr_mgmt_ultra_sleep
void pwr_mgmt_ultra_sleep(uint32_t time_ms)
Execution of this function allows ARM to enter the ultra sleep state and wakeup the chip when an even...
pwr_table
pwr_table_t pwr_table[]
pwr table.
pwr_dev_check_func_t
pwr_mgmt_dev_state_t(* pwr_dev_check_func_t)(void)
Device check function type.
Definition: gr55xx_pwr.h:142
pwr_mgmt_dev_init
void pwr_mgmt_dev_init(periph_func_t p_periph_init)
Peripheral Controller Initialization Register interface.
pwr_table_t::pwr_ext
uint16_t pwr_ext
External wake-up.
Definition: gr55xx_pwr.h:123
periph_func_t
void(* periph_func_t)(void)
Peripheral function type.
Definition: gr55xx_pwr.h:136
pwr_mgmt_load_context
void pwr_mgmt_load_context(void)
Load context function.
pwr_mgmt_var_box_t
power manager setting parameter.
Definition: gr55xx_pwr.h:72
pwr_table_t
parameter configuration table.
Definition: gr55xx_pwr.h:121
pwr_mgmt_mem_ctl_set
void pwr_mgmt_mem_ctl_set(uint32_t mem_sleep_state, uint32_t mem_work_state)
Mem state control under deep sleep & work state.
pwr_table_t::pwr_delay_hus
uint16_t pwr_delay_hus
Delay half us.
Definition: gr55xx_pwr.h:126
DEVICE_BUSY
@ DEVICE_BUSY
Device busy state.
Definition: gr55xx_pwr.h:96
boot_mode_t
boot_mode_t
power manager boot type.
Definition: gr55xx_pwr.h:80
pwr_mgmt_register_trace_func
void pwr_mgmt_register_trace_func(trace_func_t trace_func)
Trace function register.
TRC_PWR_DSLEEP_MODE
@ TRC_PWR_DSLEEP_MODE
Deep sleep mode.
Definition: gr55xx_pwr.h:111
pwr_table_t::pwr_delay_hslot
uint8_t pwr_delay_hslot
Delay half slot.
Definition: gr55xx_pwr.h:125
pwr_mgmt_check_ble_event
void pwr_mgmt_check_ble_event(void)
Check whether there are ble events in the queue, and if so, handle them immediately.
pwr_mgmt_wakeup_source_clear
void pwr_mgmt_wakeup_source_clear(uint32_t wakeup_source)
Clear the wakeup source.
pwr_mgmt_mode_get
pwr_mgmt_mode_t pwr_mgmt_mode_get(void)
Get the specified sleep mode.
pwr_mgmt_notify_timer_event
void pwr_mgmt_notify_timer_event(notify_timer_event_t timer_event)
This function is used to push startup information in app timer.
TRC_PWR_WFE_MODE
@ TRC_PWR_WFE_MODE
WFE mode.
Definition: gr55xx_pwr.h:110
TRC_PWR_APP_TIMER_REFUSE
@ TRC_PWR_APP_TIMER_REFUSE
App timer refuse.
Definition: gr55xx_pwr.h:114
pwr_mgmt_wakeup_source_setup
void pwr_mgmt_wakeup_source_setup(uint32_t wakeup_source)
Set the wakeup source.
pwr_mgmt_check_ext_timer
pwr_mgmt_mode_t pwr_mgmt_check_ext_timer(void)
Get the state of extenal timer.
notify_timer_event_t
notify_timer_event_t
power manager app timer work state.
Definition: gr55xx_pwr.h:102
pwr_mgmt_var_box_t::pwr_mgmt_rtc_timer_thrd
uint32_t pwr_mgmt_rtc_timer_thrd
RTC timer threshold.
Definition: gr55xx_pwr.h:75
WARM_BOOT
@ WARM_BOOT
Warm boot state.
Definition: gr55xx_pwr.h:82
pwr_mgmt_dev_resume
void pwr_mgmt_dev_resume(void)
Device config resume interface.
EVENT_APP_TIMER_START
@ EVENT_APP_TIMER_START
App-timer start state.
Definition: gr55xx_pwr.h:103
pwr_before_sleep_func_t
void(* pwr_before_sleep_func_t)(void)
Before sleep function type.
Definition: gr55xx_pwr.h:139
pwr_mgmt_disable_nvic_irq
void pwr_mgmt_disable_nvic_irq(void)
Disable nvic irq.
pwr_mgmt_update_wkup_param
void pwr_mgmt_update_wkup_param(void)
Update wakeup param.
pwr_table_t::pwr_timer_ths
uint32_t pwr_timer_ths
APP timer threshold.
Definition: gr55xx_pwr.h:128
pwr_mgmt_check_pend_irq
bool pwr_mgmt_check_pend_irq(void)
Check nvic irq.
pwr_mgmt_schedule
void pwr_mgmt_schedule(void)
Sleep Policy Scheduling Function.
pwr_mgmt_var_box_t::pwr_mgmt_ble_core_thrd
uint32_t pwr_mgmt_ble_core_thrd
BLE timer threshold.
Definition: gr55xx_pwr.h:74
pwr_table_t::pwr_push_hus
uint16_t pwr_push_hus
Push half us.
Definition: gr55xx_pwr.h:127
pwr_mgmt_save_context
void pwr_mgmt_save_context(void)
Save context function.
DEVICE_IDLE
@ DEVICE_IDLE
Device idle state.
Definition: gr55xx_pwr.h:97
pwr_mgmt_var_box_t::pwr_mgmt_app_timer_thrd
uint32_t pwr_mgmt_app_timer_thrd
App timer threshold.
Definition: gr55xx_pwr.h:73
PMR_MGMT_ACTIVE_MODE
@ PMR_MGMT_ACTIVE_MODE
Full speed state.
Definition: gr55xx_pwr.h:88
COLD_BOOT
@ COLD_BOOT
Cold boot state.
Definition: gr55xx_pwr.h:81
TRC_PWR_BLE_TIMER_PASS
@ TRC_PWR_BLE_TIMER_PASS
BLE timer pass.
Definition: gr55xx_pwr.h:116
pwr_mgmt_wfe_sleep
void pwr_mgmt_wfe_sleep(void)
Execution of this function allows ARM to enter the WFE state and exit the WFE state when an event or ...
pwr_mgmt_dev_state_t
pwr_mgmt_dev_state_t
power manager device work state.
Definition: gr55xx_pwr.h:95
trace_func_t
void(* trace_func_t)(uint8_t)
Trace function type.
Definition: gr55xx_pwr.h:133
pwr_mgmt_register_io_dump_func
void pwr_mgmt_register_io_dump_func(io_dump_func_t dump_func)
function registered to dump io configuration.
TRC_PWR_ACTIVE_MODE
@ TRC_PWR_ACTIVE_MODE
Active mode.
Definition: gr55xx_pwr.h:112
pwr_mgmt_get_wakeup_flag
boot_mode_t pwr_mgmt_get_wakeup_flag(void)
Get the current boot mode.
pwr_mgmt_enable_nvic_irq
void pwr_mgmt_enable_nvic_irq(void)
Enable nvic irq.
pwr_table_t::pwr_dur
uint16_t pwr_dur
Duration.
Definition: gr55xx_pwr.h:122
PMR_MGMT_SLEEP_MODE
@ PMR_MGMT_SLEEP_MODE
Deep sleep state.
Definition: gr55xx_pwr.h:90
pwr_mgmt_shutdown
pwr_mgmt_mode_t pwr_mgmt_shutdown(void)
This function allows ARM to enter deep sleep mode, but users should not use this function directly.
pwr_mgmt_set_callback
void pwr_mgmt_set_callback(pwr_dev_check_func_t dev_check_fun, pwr_before_sleep_func_t before_sleep_fun)
Set PMU callback function.
EVENT_APP_TIMER_STOP
@ EVENT_APP_TIMER_STOP
App-timer stop state.
Definition: gr55xx_pwr.h:104
pwr_mgmt_set_wakeup_flag
void pwr_mgmt_set_wakeup_flag(boot_mode_t boot_mode)
Mark the mode of next boot, cold boot or warm boot.
TRC_PWR_APP_TIMER_PASS
@ TRC_PWR_APP_TIMER_PASS
App timer pass.
Definition: gr55xx_pwr.h:115
pwr_mgmt_dev_suspend
pwr_mgmt_dev_state_t pwr_mgmt_dev_suspend(void)
Device config suspend interface.
PMR_MGMT_IDLE_MODE
@ PMR_MGMT_IDLE_MODE
Idle state.
Definition: gr55xx_pwr.h:89