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 @addtogroup Plat_SDK Platform SDK
43 @{
44 @brief Definitions and prototypes for the Platform SDK
45 */
46
47 #ifndef _PLATFORM_SDK_H
48 #define _PLATFORM_SDK_H
49
50 #include <stdint.h>
51 #include <stdbool.h>
52 #include <stdio.h>
53 #include "system_gr55xx.h"
54 #include "gr55xx_hal_def.h"
55
56 /**@addtogroup PlAT_SDK_ENUM Enumerations
57 * @{ */
58
59 /**@brief system clock and run mode. */
60 typedef enum
61 {
62 XIP_64M = 0, /**< XIP 64M. */
63 XIP_48M, /**< XIP 48M. */
64 XIP_XO16M, /**< XIP XO 16M. */
65 XIP_24M, /**< XIP 24M. */
66 XIP_16M, /**< XIP 16M. */
67 XIP_32M, /**< XIP 32M. */
68 MIRROR_64M, /**< MIRROR 64M. */
69 MIRROR_48M, /**< MIRROR 48M. */
70 MIRROR_XO16M, /**< MIRROR X) 16M. */
71 MIRROR_24M, /**< MIRROR 24M. */
72 MIRROR_16M, /**< MIRROR 16M. */
73 MIRROR_32M, /**< MIRROR 32M. */
74 } run_mode_t;
75
76 /**@brief sdk clock type. */
77 typedef enum
78 {
79 RNG_OSC_CLK = 0, /**< RNG OSC CLOCK. */
80 RTC_OSC_CLK, /**< RTC OSC CLOCK. */
81 RNG_OSC_CLK2, /**< RNG OSC CLOCK2. */
82 } sdk_clock_type_t;
83
84
85 /**@brief memory power setting mode. */
86 typedef enum
87 {
88 MEM_POWER_FULL_MODE = 0, /**< Full mode. */
89 MEM_POWER_AUTO_MODE, /**< Auto mode. */
90 } mem_power_t;
91 /** @} */
92
93 /** @addtogroup PLAT_SDK_FUNCTIONS Functions
94 * @{ */
95
96 /**
97 ****************************************************************************************
98 * @brief platform sdk init function.
99 ****************************************************************************************
100 */
101 void platform_sdk_init(void);
102
103 /**
104 ****************************************************************************************
105 * @brief Set the memory power management mode, which can be automatic mode or full power on mode.
106 * @param[in] mem_pwr_mode : MEM_POWER_FULL_MODE or MEM_POWER_AUTO_MODE.
107 * @retval : void
108 ****************************************************************************************
109 */
110 void mem_pwr_mgmt_mode_set(mem_power_t mem_pwr_mode);
111
112 /**
113 ****************************************************************************************
114 * @brief Control the memory power supply by specifying start address and length.
115 * @param[in] start_addr : the start address of memory that user want to config
116 * @param[in] size : the size of memory that user want to config
117 ****************************************************************************************
118 */
119 void mem_pwr_mgmt_mode_set_from(uint32_t start_addr, uint32_t size);
120
121 /**
122 ****************************************************************************************
123 * @brief update the counter A and counter B.
124 * @param[in] cnt_a : DCDC Stable Time.
125 * @param[in] cnt_b : Oscillator Stable Time.
126 ****************************************************************************************
127 */
128 void system_lp_counter_set(uint8_t cnt_a, uint8_t cnt_b);
129
130 /**
131 ****************************************************************************************
132 * @brief Set Time to wakeup oscillator before BLE Activity.
133 * @param[in] run_mode : run mode.
134 * @param[in] osc_us : Time Reserved for wakeup oscillator(unit: us).
135 ****************************************************************************************
136 */
137 void ble_wakeup_osc_time_set(run_mode_t run_mode, uint16_t osc_us);
138
139 /**
140 ****************************************************************************************
141 * @brief Get Time to wakeup oscillator before BLE Activity.
142 * @param[in] run_mode : run mode.
143 * @return Time Reserved for wakeup oscillator(unit: us).
144 ****************************************************************************************
145 */
146 uint16_t ble_wakeup_osc_time_get(run_mode_t run_mode);
147
148 /**
149 ****************************************************************************************
150 * @brief Get NVDS Start Address.
151 *
152 * @return The NVDS Start Address.
153 ****************************************************************************************
154 */
155 uint32_t nvds_get_start_addr(void);
156
157 /**
158 ****************************************************************************************
159 * @brief Set BLE Program Delay.
160 * @param[in] run_mode : run mode.
161 * @param[in] hslot : program delay in half slot(unit: 312.5us).
162 ****************************************************************************************
163 */
164 void ble_program_delay_set(run_mode_t run_mode, uint8_t hslot);
165
166 /**
167 ****************************************************************************************
168 * @brief Set BLE Sleep Algorithm Duration.
169 * @param[in] run_mode : run mode.
170 * @param[in] dur_hus : BLE Sleep Algorithm Duration(unit: 0.5us).
171 ****************************************************************************************
172 */
173 void ble_sleep_algo_dur_set(run_mode_t run_mode, uint16_t dur_hus);
174
175 /**
176 ****************************************************************************************
177 * @brief Set Maximum BLE Pushing Frame Time.
178 * @param[in] run_mode : run mode.
179 * @param[in] max_push_hus : maximum pushing frame time(unit: hus).
180 ****************************************************************************************
181 */
182 void ble_max_push_frame_time_set(run_mode_t run_mode, uint16_t max_push_hus);
183
184 /**
185 ****************************************************************************************
186 * @brief Set Minimum System Sleep Time.
187 * @param[in] run_mode : run mode.
188 * @param[in] min_sleep_us : Minimum Time Allowed For Sleep(unit: us).
189 ****************************************************************************************
190 */
191 void sys_min_sleep_threshold_set(run_mode_t run_mode, uint32_t min_sleep_us);
192
193 /**
194 ****************************************************************************************
195 * @brief Platform low power clock init function.
196 * @param[in] sys_clock: System clock.
197 * @param[in] clock : External RTC setting.
198 * @param[in] accuracy : Low speed clock accuracy.
199 * @param[in] xo_offset : Clock calibration parameter.
200 ****************************************************************************************
201 */
202 void platform_clock_init(mcu_clock_type_t sys_clock, sdk_clock_type_t clock, uint16_t accuracy, uint16_t xo_offset);
203
204 /**
205 ****************************************************************************************
206 * @brief Platform low power clock init function.
207 * @param[in] sys_clock: System clock.
208 * @param[in] clock : Internal RNG/RNG2 setting.
209 * @param[in] accuracy : Low speed clock accuracy.
210 * @param[in] xo_offset : Clock calibration parameter.
211 ****************************************************************************************
212 */
213 void platform_clock_init_rng(mcu_clock_type_t sys_clock, sdk_clock_type_t clock, uint16_t accuracy, uint16_t xo_offset);
214
215 /**
216 ****************************************************************************************
217 * @brief Set RTC crystal oscillator stabilization time.
218 * @param[in] wait : Delay time after RTC crystal oscillator starts.(Unit ms)
219 ****************************************************************************************
220 */
221 void platform_set_rtc_crystal_delay(uint16_t wait);
222
223 /**
224 ****************************************************************************************
225 * @brief Start RNG2 OSC calibration.
226 ****************************************************************************************
227 */
228 void platform_rng2_calibration_start(void);
229
230 /**
231 ****************************************************************************************
232 * @brief Stop RNG2 OSC calibration.
233 * @param[in] wait : True will wait calibration register is cleared
234 ****************************************************************************************
235 */
236 void platform_rng2_calibration_stop(bool wait);
237
238 /**
239 ****************************************************************************************
240 * @brief Check whether RNG2 OSC calibration is on going.
241 *
242 * @retval true calibration is on going
243 * @retval false calibration is not started or done
244 ****************************************************************************************
245 */
246 bool platform_rng2_calibration_is_busy(void);
247
248 /**
249 ****************************************************************************************
250 * @brief Get RNG2 OSC calibration result.
251 * @param[in] wait_result : true will wait calibration done to get RNG2 OSC frequency
252 * @param[in] allow_cached : true will using previous RNG2 OSC calibration frequency
253 * @return RNG2 OSC frequency in HZ
254 ****************************************************************************************
255 */
256 uint32_t platform_rng2_calibration_get(bool wait_result, bool allow_cached);
257
258 /**
259 ****************************************************************************************
260 * @brief Platform init function.
261 ****************************************************************************************
262 */
263 void platform_init(void);
264
265 /**
266 ****************************************************************************************
267 * @brief the first warm boot stage.
268 ****************************************************************************************
269 */
270 void warm_boot_first(void);
271
272 /**
273 ****************************************************************************************
274 * @brief the second warm boot stage.
275 ****************************************************************************************
276 */
277 void warm_boot_second(void);
278
279 /**
280 ****************************************************************************************
281 * @brief PMU init function.
282 * @param[in] clock_type : clock type to be configured.
283 ****************************************************************************************
284 */
285 void system_pmu_init(mcu_clock_type_t clock_type);
286
287 /**
288 ****************************************************************************************
289 * @brief PMU deinit function.
290 ****************************************************************************************
291 */
292 void system_pmu_deinit(void);
293
294 /**
295 ****************************************************************************************
296 * @brief Warm boot process.
297 ****************************************************************************************
298 */
299 void warm_boot(void);
300
301 /**
302 ****************************************************************************************
303 * @brief Set delay time between flash wakeup and read chip id in warm boot.
304 * Please referrent the time of Flash Deep Power- down to Stand-by mode.
305 * @param[in] delay_us: uinit :us
306 ****************************************************************************************
307 */
308 void warm_boot_set_exflash_readid_delay(uint32_t delay_us);
309
310 /**
311 ****************************************************************************************
312 * @brief Get delay time between flash wakeup and read chip id in warm boot.
313 * @return Delay time (unit :us)
314 ****************************************************************************************
315 */
316 uint32_t warm_boot_get_exflash_readid_delay(void);
317
318 /**
319 ****************************************************************************************
320 * @brief PMU calibration handler.
321 * @param[in] p_arg : no args.
322 ****************************************************************************************
323 */
324 void pmu_calibration_handler(void* p_arg);
325
326 /**
327 ****************************************************************************************
328 * @brief LFRC32K calibration.
329 ****************************************************************************************
330 */
331 void lfrc32k_calibration(void);
332
333 /**
334 ****************************************************************************************
335 * @brief protection platform timeout through watchdog.
336 ****************************************************************************************
337 */
338 void platform_init_push(void);
339
340 /**
341 ****************************************************************************************
342 * @brief protection platform timeout through watchdog.
343 ****************************************************************************************
344 */
345 void platform_init_pop(void);
346
347 /**
348 ****************************************************************************************
349 * @brief write flash QE
350 * @return HAL status ::hal_status_t
351 ****************************************************************************************
352 */
353 hal_status_t platform_flash_enable_quad(void);
354
355 /**
356 ****************************************************************************************
357 * @brief Power Management warm boot.
358 ****************************************************************************************
359 */
360 void pwr_mgmt_warm_boot(void);
361
362 /** @} */
363
364 #endif
365
366 /** @} */
367 /** @} */
368
MIRROR_32M
@ MIRROR_32M
MIRROR 32M.
Definition: platform_sdk.h:73
MIRROR_24M
@ MIRROR_24M
MIRROR 24M.
Definition: platform_sdk.h:71
platform_clock_init_rng
void platform_clock_init_rng(mcu_clock_type_t sys_clock, sdk_clock_type_t clock, uint16_t accuracy, uint16_t xo_offset)
Platform low power clock init function.
ble_max_push_frame_time_set
void ble_max_push_frame_time_set(run_mode_t run_mode, uint16_t max_push_hus)
Set Maximum BLE Pushing Frame Time.
RNG_OSC_CLK
@ RNG_OSC_CLK
RNG OSC CLOCK.
Definition: platform_sdk.h:79
platform_clock_init
void platform_clock_init(mcu_clock_type_t sys_clock, sdk_clock_type_t clock, uint16_t accuracy, uint16_t xo_offset)
Platform low power clock init function.
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.
platform_rng2_calibration_is_busy
bool platform_rng2_calibration_is_busy(void)
Check whether RNG2 OSC calibration is on going.
MEM_POWER_AUTO_MODE
@ MEM_POWER_AUTO_MODE
Auto mode.
Definition: platform_sdk.h:89
XIP_32M
@ XIP_32M
XIP 32M.
Definition: platform_sdk.h:67
lfrc32k_calibration
void lfrc32k_calibration(void)
LFRC32K calibration.
platform_init_pop
void platform_init_pop(void)
protection platform timeout through watchdog.
XIP_XO16M
@ XIP_XO16M
XIP XO 16M.
Definition: platform_sdk.h:64
platform_sdk_init
void platform_sdk_init(void)
platform sdk init function.
MIRROR_XO16M
@ MIRROR_XO16M
MIRROR X) 16M.
Definition: platform_sdk.h:70
platform_flash_enable_quad
hal_status_t platform_flash_enable_quad(void)
write flash QE
mem_power_t
mem_power_t
memory power setting mode.
Definition: platform_sdk.h:87
RNG_OSC_CLK2
@ RNG_OSC_CLK2
RNG OSC CLOCK2.
Definition: platform_sdk.h:81
nvds_get_start_addr
uint32_t nvds_get_start_addr(void)
Get NVDS Start Address.
delay_us
__STATIC_FORCEINLINE void delay_us(uint32_t number_of_us)
Function for delaying execution for number of us.
Definition: gr55xx_delay.h:144
XIP_64M
@ XIP_64M
XIP 64M.
Definition: platform_sdk.h:62
sys_min_sleep_threshold_set
void sys_min_sleep_threshold_set(run_mode_t run_mode, uint32_t min_sleep_us)
Set Minimum System Sleep Time.
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.
platform_rng2_calibration_stop
void platform_rng2_calibration_stop(bool wait)
Stop RNG2 OSC calibration.
MIRROR_48M
@ MIRROR_48M
MIRROR 48M.
Definition: platform_sdk.h:69
platform_set_rtc_crystal_delay
void platform_set_rtc_crystal_delay(uint16_t wait)
Set RTC crystal oscillator stabilization time.
run_mode_t
run_mode_t
system clock and run mode.
Definition: platform_sdk.h:61
platform_init
void platform_init(void)
Platform init function.
ble_wakeup_osc_time_get
uint16_t ble_wakeup_osc_time_get(run_mode_t run_mode)
Get Time to wakeup oscillator before BLE Activity.
system_pmu_init
void system_pmu_init(mcu_clock_type_t clock_type)
PMU init function.
ble_program_delay_set
void ble_program_delay_set(run_mode_t run_mode, uint8_t hslot)
Set BLE Program Delay.
MIRROR_64M
@ MIRROR_64M
MIRROR 64M.
Definition: platform_sdk.h:68
warm_boot_second
void warm_boot_second(void)
the second warm boot stage.
XIP_48M
@ XIP_48M
XIP 48M.
Definition: platform_sdk.h:63
RTC_OSC_CLK
@ RTC_OSC_CLK
RTC OSC CLOCK.
Definition: platform_sdk.h:80
warm_boot_set_exflash_readid_delay
void warm_boot_set_exflash_readid_delay(uint32_t delay_us)
Set delay time between flash wakeup and read chip id in warm boot.
MIRROR_16M
@ MIRROR_16M
MIRROR 16M.
Definition: platform_sdk.h:72
hal_status_t
hal_status_t
HAL Status structures definition.
Definition: gr55xx_hal_def.h:70
ble_wakeup_osc_time_set
void ble_wakeup_osc_time_set(run_mode_t run_mode, uint16_t osc_us)
Set Time to wakeup oscillator before BLE Activity.
MEM_POWER_FULL_MODE
@ MEM_POWER_FULL_MODE
Full mode.
Definition: platform_sdk.h:88
platform_rng2_calibration_get
uint32_t platform_rng2_calibration_get(bool wait_result, bool allow_cached)
Get RNG2 OSC calibration result.
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.
platform_init_push
void platform_init_push(void)
protection platform timeout through watchdog.
system_lp_counter_set
void system_lp_counter_set(uint8_t cnt_a, uint8_t cnt_b)
update the counter A and counter B.
warm_boot
void warm_boot(void)
Warm boot process.
platform_rng2_calibration_start
void platform_rng2_calibration_start(void)
Start RNG2 OSC calibration.
XIP_16M
@ XIP_16M
XIP 16M.
Definition: platform_sdk.h:66
XIP_24M
@ XIP_24M
XIP 24M.
Definition: platform_sdk.h:65
system_pmu_deinit
void system_pmu_deinit(void)
PMU deinit function.
warm_boot_get_exflash_readid_delay
uint32_t warm_boot_get_exflash_readid_delay(void)
Get delay time between flash wakeup and read chip id in warm boot.
ble_sleep_algo_dur_set
void ble_sleep_algo_dur_set(run_mode_t run_mode, uint16_t dur_hus)
Set BLE Sleep Algorithm Duration.
gr55xx_hal_def.h
This file contains HAL common definitions, enumeration, macros and structures definitions.
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:78