platform_sdk.h
Go to the documentation of this file.
1 /**
2  ******************************************************************************
3  *
4  * @file platform_sdk.h
5  *
6  ****************************************************************************************
7  * @attention
8  #####Copyright (c) 2019 GOODIX
9  All rights reserved.
10 
11  Redistribution and use in source and binary forms, with or without
12  modification, are permitted provided that the following conditions are met:
13  * Redistributions of source code must retain the above copyright
14  notice, this list of conditions and the following disclaimer.
15  * Redistributions in binary form must reproduce the above copyright
16  notice, this list of conditions and the following disclaimer in the
17  documentation and/or other materials provided with the distribution.
18  * Neither the name of GOODIX nor the names of its contributors may be used
19  to endorse or promote products derived from this software without
20  specific prior written permission.
21 
22  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
26  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32  POSSIBILITY OF SUCH DAMAGE.
33  *****************************************************************************************
34  */
35 
36 
37 /**
38  * @addtogroup SYSTEM
39  * @{
40  */
41 
42 /**
43  * @addtogroup Plat_SDK Platform SDK
44  * @{
45  * @brief Definitions and prototypes for the Platform SDK
46  */
47 
48 #ifndef _PLATFORM_SDK_H
49 #define _PLATFORM_SDK_H
50 
51 #include <stdint.h>
52 #include <stdbool.h>
53 #include <stdio.h>
54 #include "system_gr55xx.h"
55 #include "gr55xx_hal_def.h"
56 #include "gr55xx_hal.h"
57 
58 /**
59  * @defgroup PlAT_SDK_MACRO Defines
60  * @{
61  */
62 
63 /** @brief Clock calibration macro. */
64 #define XO_CRYSTAL_FREQ 32000000 //XO 32MHz
65 #define CLK_CAL_STAT_BUSY 0x00
66 #define CLK_CAL_STAT_DONE 0x01
67 #define CLK_CAL_STAT_OVERFLOW 0x100
68 /** @} */
69 
70 /** @addtogroup PlAT_SDK_ENUM Enumerations
71  * @{ */
72 
73 /** @brief system clock and run mode. */
74 typedef enum
75 {
76  XIP_64M = 0, /**< XIP 64M. */
77  XIP_48M, /**< XIP 48M. */
78  XIP_XO16M, /**< XIP XO 16M. */
79  XIP_24M, /**< XIP 24M. */
80  XIP_16M, /**< XIP 16M. */
81  XIP_32M, /**< XIP 32M. */
82  MIRROR_64M, /**< MIRROR 64M. */
83  MIRROR_48M, /**< MIRROR 48M. */
84  MIRROR_XO16M, /**< MIRROR X) 16M. */
85  MIRROR_24M, /**< MIRROR 24M. */
86  MIRROR_16M, /**< MIRROR 16M. */
87  MIRROR_32M, /**< MIRROR 32M. */
88 } table_idx_t;
89 
90 /** @brief sdk clock type. */
91 typedef enum
92 {
93  RNG_OSC_CLK = 0, /**< RNG OSC CLOCK. */
94  RTC_OSC_CLK, /**< RTC OSC CLOCK. */
95  RNG_OSC_CLK2, /**< RNG OSC CLOCK2. */
96 } sdk_clock_type_t;
97 
98 
99 /** @brief memory power setting mode. */
100 typedef enum
101 {
102  MEM_POWER_FULL_MODE = 0, /**< Full mode. */
103  MEM_POWER_AUTO_MODE, /**< Auto mode. */
104 } mem_power_t;
105  /** @} */
106 
107 /**
108 * @defgroup PLAT_SDK_TYPEDEFS Type definitions
109 * @{
110 */
111 
112 /**@brief clock calibration notify callback. */
113 typedef void (*clock_calib_notify_cb_t)(float SlowClockFreq);
114 
115 /** @} */
116 
117 /** @addtogroup PLAT_SDK_FUNCTIONS Functions
118  * @{ */
119 
120 /**
121  ****************************************************************************************
122  * @brief platform sdk init function.
123  ****************************************************************************************
124  */
125 void platform_sdk_init(void);
126 
127 /**
128  ****************************************************************************************
129  * @brief Set the memory power management mode, which can be automatic mode or full power on mode.
130  * @param[in] mem_pwr_mode : MEM_POWER_FULL_MODE or MEM_POWER_AUTO_MODE.
131  ****************************************************************************************
132  */
133 void mem_pwr_mgmt_mode_set(mem_power_t mem_pwr_mode);
134 
135 /**
136  ****************************************************************************************
137  * @brief Control the memory power supply by specifying start address and length.
138  * @param[in] start_addr : the start address of memory that user want to config
139  * @param[in] size : the size of memory that user want to config
140  ****************************************************************************************
141  */
142 void mem_pwr_mgmt_mode_set_from(uint32_t start_addr, uint32_t size);
143 
144 /**
145  ****************************************************************************************
146  * @brief Enable patch function.
147  * @param[in] table_idx : Start Index Number.
148  * @param[in] dur_offset : duration setting.
149  * @param[in] ext_offset : ext wakeup setting.
150  * @param[in] osc_offset : pre-wakeup setting.
151  ****************************************************************************************
152  */
153 void system_lp_table_update_twval(table_idx_t table_idx, int16_t dur_offset, int16_t ext_offset, int16_t osc_offset);
154 
155 /**
156  ****************************************************************************************
157  * @brief Platform low power clock init function with internal RNG/RNG2 setting.
158  * @param[in] sys_clock System clock.
159  * @param[in] accuracy Low speed clock accuracy.
160  * @param[in] xo_offset Clock calibration parameter.
161  ****************************************************************************************
162  */
163 void platform_clock_init_with_rng2(mcu_clock_type_t sys_clock, uint16_t accuracy, uint16_t xo_offset);
164 
165 /**
166  ****************************************************************************************
167  * @brief Platform low power clock init function with External RTC setting.
168  * @param[in] sys_clock: System clock.
169  * @param[in] accuracy : Low speed clock accuracy.
170  * @param[in] xo_offset : Clock calibration parameter.
171  ****************************************************************************************
172  */
173 void platform_clock_init_with_rtc(mcu_clock_type_t sys_clock, uint16_t accuracy, uint16_t xo_offset);
174 
175 /**
176  ****************************************************************************************
177  * @brief Platform rc calibration function.
178  ****************************************************************************************
179  */
180 void platform_rc_calibration(void);
181 
182 /**
183  ****************************************************************************************
184  * @brief Power Management warm boot.
185  ****************************************************************************************
186  */
187 void pwr_mgmt_warm_boot(void);
188 
189 /**
190  ****************************************************************************************
191  * @brief Handle Clock calibration interrupt request.
192  ****************************************************************************************
193  */
194 void clock_calibration_irq_handler(void);
195 
196 /**
197  ****************************************************************************************
198  * @brief update comm wakeup timing settings according to lf clock
199  * @retval : void
200  ****************************************************************************************
201  */
202 void pwr_mgmt_update_comm_wkup_timing_param(void);
203 
204 /**
205  ****************************************************************************************
206  * @brief Platform init function.
207  ****************************************************************************************
208  */
209 void platform_init(void);
210 
211 /**
212  ****************************************************************************************
213  * @brief PMU init function.
214  * @param[in] clock_type : clock type to be configured.
215  ****************************************************************************************
216  */
217 void system_pmu_init(mcu_clock_type_t clock_type);
218 
219 /**
220  ****************************************************************************************
221  * @brief PMU increase function, will increase about 0.35v digcore
222  ****************************************************************************************
223  */
224 bool system_pmu_increase_for_peripheral(void);
225 
226 /**
227  ****************************************************************************************
228  * @brief PMU restore function.
229  * When wanting to use higher digcore voltage, call system_pmu_increase_for_peripheral(),
230  * when no need use higher voltage anymore, call system_pmu_restore_for_peripheral().
231  ****************************************************************************************
232  */
233 bool system_pmu_restore_for_peripheral(void);
234 
235 /**
236  ****************************************************************************************
237  * @brief the first warm boot stage.
238  ****************************************************************************************
239  */
240 void warm_boot_first(void);
241 
242  /**
243  ****************************************************************************************
244  * @brief the second warm boot stage.
245  ****************************************************************************************
246  */
247 void warm_boot_second(void);
248 
249 /**
250  ****************************************************************************************
251  * @brief Warm boot process.
252  ****************************************************************************************
253  */
254 void warm_boot(void);
255 
256 /**
257  ****************************************************************************************
258  * @brief PMU calibration handler.
259  * @param[in] p_arg no args.
260  ****************************************************************************************
261  */
262 void pmu_calibration_handler(void* p_arg);
263 
264 /**
265  ****************************************************************************************
266  * @brief Register the clock calibration completion callback.
267  * @param[in] calib_notify_cb : Calibration completion callback.
268  *
269  * @retval ::SDK_SUCCESS: Register callback Successfully.
270  * @retval ::SDK_ERR_POINTER_NULL: calib_notify_cb is null pointer.
271  * @retval ::SDK_ERR_LIST_FULL: Operation is failed, the clock calibration completion callback is full.
272  ****************************************************************************************
273  */
274 uint16_t clock_calib_notify_register(clock_calib_notify_cb_t calib_notify_cb);
275 
276 /**
277  ****************************************************************************************
278  * @brief Unregister the clock calibration completion callback.
279  * @param[in] calib_notify_cb : Calibration completion callback.
280  *
281  * @retval ::SDK_SUCCESS: Unregister callback Successfully.
282  * @retval ::SDK_ERR_POINTER_NULL: calib_notify_cb is null pointer.
283  * @retval ::SDK_ERR_LIST_ITEM_NOT_FOUND: Operation is failed, the clock calibration completion has not been registered.
284  ****************************************************************************************
285  */
286 uint16_t clock_calib_notify_unregister(clock_calib_notify_cb_t calib_notify_cb);
287 
288 #ifdef ENV_USE_FREERTOS
289 /**
290  ****************************************************************************************
291  * @brief start calibration.
292  ****************************************************************************************
293  */
294 void system_pmu_calibration_start(void);
295 #else
296 /**
297  ****************************************************************************************
298  * @brief start calibration.
299  * @param[in] interval : the interval of calibration process.
300  ****************************************************************************************
301  */
302 void system_pmu_calibration_start(uint32_t interval);
303 #endif
304 
305 /**
306  ****************************************************************************************
307  * @brief stop calibration.
308  ****************************************************************************************
309  */
310 void system_pmu_calibration_stop(void);
311 
312 /**
313  ****************************************************************************************
314  * @brief write flash QE
315  * @returns hal status
316  ****************************************************************************************
317  */
318 hal_status_t platform_flash_enable_quad(exflash_hp_init_t *hp_init);
319 
320 /** @} */
321 
322 #endif
323 
324 /** @} */
325 /** @} */
326 
system_pmu_calibration_stop
void system_pmu_calibration_stop(void)
stop calibration.
XIP_16M
@ XIP_16M
XIP 16M.
Definition: platform_sdk.h:80
platform_rc_calibration
void platform_rc_calibration(void)
Platform rc calibration function.
RNG_OSC_CLK
@ RNG_OSC_CLK
RNG OSC CLOCK.
Definition: platform_sdk.h:93
clock_calib_notify_register
uint16_t clock_calib_notify_register(clock_calib_notify_cb_t calib_notify_cb)
Register the clock calibration completion callback.
MIRROR_32M
@ MIRROR_32M
MIRROR 32M.
Definition: platform_sdk.h:87
mem_pwr_mgmt_mode_set_from
void mem_pwr_mgmt_mode_set_from(uint32_t start_addr, uint32_t size)
Control the memory power supply by specifying start address and length.
pwr_mgmt_update_comm_wkup_timing_param
void pwr_mgmt_update_comm_wkup_timing_param(void)
update comm wakeup timing settings according to lf clock
MIRROR_24M
@ MIRROR_24M
MIRROR 24M.
Definition: platform_sdk.h:85
MEM_POWER_AUTO_MODE
@ MEM_POWER_AUTO_MODE
Auto mode.
Definition: platform_sdk.h:103
XIP_24M
@ XIP_24M
XIP 24M.
Definition: platform_sdk.h:79
_ll_xqspi_hp_init_t
XQSPI High Performance mode init structures definition.
Definition: gr55xx_ll_xqspi.h:77
platform_sdk_init
void platform_sdk_init(void)
platform sdk init function.
mem_power_t
mem_power_t
memory power setting mode.
Definition: platform_sdk.h:101
XIP_32M
@ XIP_32M
XIP 32M.
Definition: platform_sdk.h:81
RNG_OSC_CLK2
@ RNG_OSC_CLK2
RNG OSC CLOCK2.
Definition: platform_sdk.h:95
system_pmu_calibration_start
void system_pmu_calibration_start(uint32_t interval)
start calibration.
system_pmu_increase_for_peripheral
bool system_pmu_increase_for_peripheral(void)
PMU increase function, will increase about 0.35v digcore.
mem_pwr_mgmt_mode_set
void mem_pwr_mgmt_mode_set(mem_power_t mem_pwr_mode)
Set the memory power management mode, which can be automatic mode or full power on mode.
MIRROR_64M
@ MIRROR_64M
MIRROR 64M.
Definition: platform_sdk.h:82
MIRROR_16M
@ MIRROR_16M
MIRROR 16M.
Definition: platform_sdk.h:86
clock_calib_notify_cb_t
void(* clock_calib_notify_cb_t)(float SlowClockFreq)
clock calibration notify callback.
Definition: platform_sdk.h:113
table_idx_t
table_idx_t
system clock and run mode.
Definition: platform_sdk.h:75
platform_init
void platform_init(void)
Platform init function.
platform_clock_init_with_rtc
void platform_clock_init_with_rtc(mcu_clock_type_t sys_clock, uint16_t accuracy, uint16_t xo_offset)
Platform low power clock init function with External RTC setting.
platform_flash_enable_quad
hal_status_t platform_flash_enable_quad(exflash_hp_init_t *hp_init)
write flash QE
system_pmu_init
void system_pmu_init(mcu_clock_type_t clock_type)
PMU init function.
warm_boot_second
void warm_boot_second(void)
the second warm boot stage.
RTC_OSC_CLK
@ RTC_OSC_CLK
RTC OSC CLOCK.
Definition: platform_sdk.h:94
clock_calibration_irq_handler
void clock_calibration_irq_handler(void)
Handle Clock calibration interrupt request.
clock_calib_notify_unregister
uint16_t clock_calib_notify_unregister(clock_calib_notify_cb_t calib_notify_cb)
Unregister the clock calibration completion callback.
XIP_48M
@ XIP_48M
XIP 48M.
Definition: platform_sdk.h:77
hal_status_t
hal_status_t
HAL Status structures definition.
Definition: gr55xx_hal_def.h:70
MIRROR_48M
@ MIRROR_48M
MIRROR 48M.
Definition: platform_sdk.h:83
gr55xx_hal.h
This file contains all the functions prototypes for the HAL module driver.
MEM_POWER_FULL_MODE
@ MEM_POWER_FULL_MODE
Full mode.
Definition: platform_sdk.h:102
XIP_64M
@ XIP_64M
XIP 64M.
Definition: platform_sdk.h:76
warm_boot_first
void warm_boot_first(void)
the first warm boot stage.
pwr_mgmt_warm_boot
void pwr_mgmt_warm_boot(void)
Power Management warm boot.
warm_boot
void warm_boot(void)
Warm boot process.
system_pmu_restore_for_peripheral
bool system_pmu_restore_for_peripheral(void)
PMU restore function.
MIRROR_XO16M
@ MIRROR_XO16M
MIRROR X) 16M.
Definition: platform_sdk.h:84
xo_offset
uint16_t xo_offset
Definition: gr55xx_efuse_layout.h:5
system_lp_table_update_twval
void system_lp_table_update_twval(table_idx_t table_idx, int16_t dur_offset, int16_t ext_offset, int16_t osc_offset)
Enable patch function.
gr55xx_hal_def.h
This file contains HAL common definitions, enumeration, macros and structures definitions.
XIP_XO16M
@ XIP_XO16M
XIP XO 16M.
Definition: platform_sdk.h:78
platform_clock_init_with_rng2
void platform_clock_init_with_rng2(mcu_clock_type_t sys_clock, uint16_t accuracy, uint16_t xo_offset)
Platform low power clock init function with internal RNG/RNG2 setting.
pmu_calibration_handler
void pmu_calibration_handler(void *p_arg)
PMU calibration handler.
sdk_clock_type_t
sdk_clock_type_t
sdk clock type.
Definition: platform_sdk.h:92