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