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  ****************************************************************************************
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 During Flash erase/write operation, Disable external interrupts with a priority less
358  * than or equal to base_priority in the system.
359  * @param[in] base_priority: Base Priority value to set.
360  * @return HAL status ::hal_status_t
361  ****************************************************************************************
362  */
363 hal_status_t platform_flash_protection(uint32_t base_priority);
364 
365 /**
366  ****************************************************************************************
367  * @brief protection interrupt handler during writing/erasing flash.
368  * @return HAL status ::hal_status_t
369  ****************************************************************************************
370  */
371 hal_status_t platform_interrupt_protection_push(void);
372 
373 /**
374  ****************************************************************************************
375  * @brief protection interrupt handler during writing/erasing flash.
376  * @return HAL status ::hal_status_t
377  ****************************************************************************************
378  */
379 hal_status_t platform_interrupt_protection_pop(void);
380 
381 /**
382  ****************************************************************************************
383  * @brief Power Management warm boot.
384  ****************************************************************************************
385  */
386 void pwr_mgmt_warm_boot(void);
387 
388 /** @} */
389 
390 #endif
391 
392 /** @} */
393 /** @} */
394 
mem_pwr_mgmt_full_power_set
void mem_pwr_mgmt_full_power_set(void)
set the memory power state to full. This function is mainly used in some scenarios where all SRAMs ne...
MIRROR_32M
@ MIRROR_32M
Definition: platform_sdk.h:73
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
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
Definition: platform_sdk.h:89
XIP_32M
@ XIP_32M
Definition: platform_sdk.h:67
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
Definition: platform_sdk.h:64
platform_sdk_init
void platform_sdk_init(void)
platform sdk init function.
MIRROR_XO16M
@ MIRROR_XO16M
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
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
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
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
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
Definition: platform_sdk.h:63
RTC_OSC_CLK
@ RTC_OSC_CLK
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. Please referrent the time of Flash...
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
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
Definition: platform_sdk.h:66
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