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 state to full. This function is mainly used in some
106 * scenarios where all SRAMs need to be powered on
107 ****************************************************************************************
108 */
109 void mem_pwr_mgmt_full_power_set(void);
110
111 /**
112 ****************************************************************************************
113 * @brief Control the memory power supply by specifying start address and length.
114 * @param[in] start_addr : the start address of memory that user want to config
115 * @param[in] size : the size of memory that user want to config
116 ****************************************************************************************
117 */
118 void mem_pwr_mgmt_mode_set_from(uint32_t start_addr, uint32_t size);
119
120 /**
121 ****************************************************************************************
122 * @brief memory check process
123 ****************************************************************************************
124 */
125 void mem_pwr_mgmt_init(void);
126
127 /**
128 ****************************************************************************************
129 * @brief update the counter A and counter B.
130 * @param[in] cnt_a : DCDC Stable Time.
131 * @param[in] cnt_b : Oscillator Stable Time.
132 ****************************************************************************************
133 */
134 void system_lp_counter_set(uint8_t cnt_a, uint8_t cnt_b);
135
136 /**
137 ****************************************************************************************
138 * @brief Set Time to wakeup oscillator before BLE Activity.
139 * @param[in] run_mode : run mode.
140 * @param[in] osc_us : Time Reserved for wakeup oscillator(unit: us).
141 ****************************************************************************************
142 */
143 void ble_wakeup_osc_time_set(run_mode_t run_mode, uint16_t osc_us);
144
145 /**
146 ****************************************************************************************
147 * @brief Get Time to wakeup oscillator before BLE Activity.
148 * @param[in] run_mode : run mode.
149 * @return Time Reserved for wakeup oscillator(unit: us).
150 ****************************************************************************************
151 */
152 uint16_t ble_wakeup_osc_time_get(run_mode_t run_mode);
153
154 /**
155 ****************************************************************************************
156 * @brief Get NVDS Start Address.
157 *
158 * @return The NVDS Start Address.
159 ****************************************************************************************
160 */
161 uint32_t nvds_get_start_addr(void);
162
163 /**
164 ****************************************************************************************
165 * @brief Set BLE Program Delay.
166 * @param[in] run_mode : run mode.
167 * @param[in] hslot : program delay in half slot(unit: 312.5us).
168 ****************************************************************************************
169 */
170 void ble_program_delay_set(run_mode_t run_mode, uint8_t hslot);
171
172 /**
173 ****************************************************************************************
174 * @brief Set BLE Sleep Algorithm Duration.
175 * @param[in] run_mode : run mode.
176 * @param[in] dur_hus : BLE Sleep Algorithm Duration(unit: 0.5us).
177 ****************************************************************************************
178 */
179 void ble_sleep_algo_dur_set(run_mode_t run_mode, uint16_t dur_hus);
180
181 /**
182 ****************************************************************************************
183 * @brief Set Maximum BLE Pushing Frame Time.
184 * @param[in] run_mode : run mode.
185 * @param[in] max_push_hus : maximum pushing frame time(unit: hus).
186 ****************************************************************************************
187 */
188 void ble_max_push_frame_time_set(run_mode_t run_mode, uint16_t max_push_hus);
189
190 /**
191 ****************************************************************************************
192 * @brief Set Minimum System Sleep Time.
193 * @param[in] run_mode : run mode.
194 * @param[in] min_sleep_us : Minimum Time Allowed For Sleep(unit: us).
195 ****************************************************************************************
196 */
197 void sys_min_sleep_threshold_set(run_mode_t run_mode, uint32_t min_sleep_us);
198
199 /**
200 ****************************************************************************************
201 * @brief Platform low power clock init function.
202 * @param[in] sys_clock: System clock.
203 * @param[in] clock : External RTC setting.
204 * @param[in] accuracy : Low speed clock accuracy.
205 * @param[in] xo_offset : Clock calibration parameter.
206 ****************************************************************************************
207 */
208 void platform_clock_init(mcu_clock_type_t sys_clock, sdk_clock_type_t clock, uint16_t accuracy, uint16_t xo_offset);
209
210 /**
211 ****************************************************************************************
212 * @brief Platform low power clock init function.
213 * @param[in] sys_clock: System clock.
214 * @param[in] clock : Internal RNG/RNG2 setting.
215 * @param[in] accuracy : Low speed clock accuracy.
216 * @param[in] xo_offset : Clock calibration parameter.
217 ****************************************************************************************
218 */
219 void platform_clock_init_rng(mcu_clock_type_t sys_clock, sdk_clock_type_t clock, uint16_t accuracy, uint16_t xo_offset);
220
221 /**
222 ****************************************************************************************
223 * @brief Set RTC crystal oscillator stabilization time.
224 * @param[in] wait : Delay time after RTC crystal oscillator starts.(Unit ms)
225 ****************************************************************************************
226 */
227 void platform_set_rtc_crystal_delay(uint16_t wait);
228
229 /**
230 ****************************************************************************************
231 * @brief Start RNG2 OSC calibration.
232 ****************************************************************************************
233 */
234 void platform_rng2_calibration_start(void);
235
236 /**
237 ****************************************************************************************
238 * @brief Stop RNG2 OSC calibration.
239 * @param[in] wait : True will wait calibration register is cleared
240 ****************************************************************************************
241 */
242 void platform_rng2_calibration_stop(bool wait);
243
244 /**
245 ****************************************************************************************
246 * @brief Check whether RNG2 OSC calibration is on going.
247 *
248 * @retval true calibration is on going
249 * @retval false calibration is not started or done
250 ****************************************************************************************
251 */
252 bool platform_rng2_calibration_is_busy(void);
253
254 /**
255 ****************************************************************************************
256 * @brief Get RNG2 OSC calibration result.
257 * @param[in] wait_result : true will wait calibration done to get RNG2 OSC frequency
258 * @param[in] allow_cached : true will using previous RNG2 OSC calibration frequency
259 * @return RNG2 OSC frequency in HZ
260 ****************************************************************************************
261 */
262 uint32_t platform_rng2_calibration_get(bool wait_result, bool allow_cached);
263
264 /**
265 ****************************************************************************************
266 * @brief Platform init function.
267 ****************************************************************************************
268 */
269 void platform_init(void);
270
271 /**
272 ****************************************************************************************
273 * @brief the first warm boot stage.
274 ****************************************************************************************
275 */
276 void warm_boot_first(void);
277
278 /**
279 ****************************************************************************************
280 * @brief the second warm boot stage.
281 ****************************************************************************************
282 */
283 void warm_boot_second(void);
284
285 /**
286 ****************************************************************************************
287 * @brief PMU init function.
288 * @param[in] clock_type : clock type to be configured.
289 ****************************************************************************************
290 */
291 void system_pmu_init(mcu_clock_type_t clock_type);
292
293 /**
294 ****************************************************************************************
295 * @brief PMU deinit function.
296 ****************************************************************************************
297 */
298 void system_pmu_deinit(void);
299
300 /**
301 ****************************************************************************************
302 * @brief Warm boot process.
303 ****************************************************************************************
304 */
305 void warm_boot(void);
306
307 /**
308 ****************************************************************************************
309 * @brief Set delay time between flash wakeup and read chip id in warm boot.
310 * Please referrent the time of Flash Deep Power- down to Stand-by mode.
311 * @param[in] delay_us: uinit :us
312 ****************************************************************************************
313 */
314 void warm_boot_set_exflash_readid_delay(uint32_t delay_us);
315
316 /**
317 ****************************************************************************************
318 * @brief Get delay time between flash wakeup and read chip id in warm boot.
319 * @return Delay time (unit :us)
320 ****************************************************************************************
321 */
322 uint32_t warm_boot_get_exflash_readid_delay(void);
323
324 /**
325 ****************************************************************************************
326 * @brief PMU calibration handler.
327 * @param[in] p_arg : no args.
328 ****************************************************************************************
329 */
330 void pmu_calibration_handler(void* p_arg);
331
332 /**
333 ****************************************************************************************
334 * @brief LFRC32K calibration.
335 ****************************************************************************************
336 */
337 void lfrc32k_calibration(void);
338
339 /**
340 ****************************************************************************************
341 * @brief protection platform timeout through watchdog.
342 ****************************************************************************************
343 */
344 void platform_init_push(void);
345
346 /**
347 ****************************************************************************************
348 * @brief protection platform timeout through watchdog.
349 ****************************************************************************************
350 */
351 void platform_init_pop(void);
352
353 /**
354 ****************************************************************************************
355 * @brief write flash QE
356 * @return HAL status ::hal_status_t
357 ****************************************************************************************
358 */
359 hal_status_t platform_flash_enable_quad(void);
360
361 /**
362 ****************************************************************************************
363 * @brief During Flash erase/write operation, Disable external interrupts with a priority less
364 * than or equal to base_priority in the system.
365 * @param[in] base_priority: Base Priority value to set.
366 * @return HAL status ::hal_status_t
367 ****************************************************************************************
368 */
369 hal_status_t platform_flash_protection(uint32_t base_priority);
370
371 /**
372 ****************************************************************************************
373 * @brief protection interrupt handler during writing/erasing flash.
374 * @return HAL status ::hal_status_t
375 ****************************************************************************************
376 */
377 hal_status_t platform_interrupt_protection_push(void);
378
379 /**
380 ****************************************************************************************
381 * @brief protection interrupt handler during writing/erasing flash.
382 * @return HAL status ::hal_status_t
383 ****************************************************************************************
384 */
385 hal_status_t platform_interrupt_protection_pop(void);
386
387 /**
388 ****************************************************************************************
389 * @brief Power Management warm boot.
390 ****************************************************************************************
391 */
392 void pwr_mgmt_warm_boot(void);
393
394 /** @} */
395
396 #endif
397
398 /** @} */
399 /** @} */
400
mem_pwr_mgmt_full_power_set
void mem_pwr_mgmt_full_power_set(void)
set the memory power state to full.
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_interrupt_protection_push
hal_status_t platform_interrupt_protection_push(void)
protection interrupt handler during writing/erasing flash.
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.
mem_pwr_mgmt_init
void mem_pwr_mgmt_init(void)
memory check process
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:154
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.
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
platform_flash_protection
hal_status_t platform_flash_protection(uint32_t base_priority)
During Flash erase/write operation, Disable external interrupts with a priority less than or equal to...
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.
platform_interrupt_protection_pop
hal_status_t platform_interrupt_protection_pop(void)
protection interrupt handler during writing/erasing flash.
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