Goodix
GR551x API Reference  V1_6_06_B5676
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 sys_wakeup_osc_time_set(run_mode_t run_mode, uint16_t osc_us);
150 
151 /**
152  ****************************************************************************************
153  * @brief Set BLE Program Delay.
154  * @param[in] run_mode : run mode.
155  * @param[in] hslot : program delay in half slot(unit: 312.5us).
156  * @retval : void
157  ****************************************************************************************
158  */
159 void ble_program_delay_set(run_mode_t run_mode, uint8_t hslot);
160 
161 /**
162  ****************************************************************************************
163  * @brief Set BLE Sleep Algorithm Duration.
164  * @param[in] run_mode : run mode.
165  * @param[in] dur_hus : BLE Sleep Algorithm Duration(unit: 0.5us).
166  * @retval : void
167  ****************************************************************************************
168  */
169 void ble_sleep_algo_dur_set(run_mode_t run_mode, uint8_t dur_hus);
170 
171 /**
172  ****************************************************************************************
173  * @brief Set Maximum BLE Pushing Frame Time.
174  * @param[in] run_mode : run mode.
175  * @param[in] max_push_hus : maximum pushing frame time(unit: hus).
176  * @retval : void
177  ****************************************************************************************
178  */
179 void ble_max_push_frame_time_set(run_mode_t run_mode, uint8_t max_push_hus);
180 
181 /**
182  ****************************************************************************************
183  * @brief Set Minimum System Sleep Time.
184  * @param[in] run_mode : run mode.
185  * @param[in] min_sleep_us : Minimum Time Allowed For Sleep(unit: us).
186  * @retval : void
187  ****************************************************************************************
188  */
189 void sys_min_sleep_threshold_set(run_mode_t run_mode, uint32_t min_sleep_us);
190 
191 /**
192  ****************************************************************************************
193  * @brief Platform low power clock init function.
194  * @param[in] sys_clock: System clock.
195  * @param[in] clock : External RTC setting or internal RNG/RNG2 setting.
196  * @param[in] accuracy : Low speed clock accuracy.
197  * @param[in] xo_offset : Clock calibration parameter.
198  * @retval : void
199  ****************************************************************************************
200  */
201 void platform_clock_init(mcu_clock_type_t sys_clock, sdk_clock_type_t clock, uint16_t accuracy, uint16_t xo_offset);
202 
203 /**
204  ****************************************************************************************
205  * @brief Start RNG2 OSC calibration.
206  * @retval : void
207  ****************************************************************************************
208  */
210 
211 /**
212  ****************************************************************************************
213  * @brief Stop RNG2 OSC calibration.
214  * @param[in] wait : True will wait calibration register is cleared
215  * @retval : void
216  ****************************************************************************************
217  */
219 
220 /**
221  ****************************************************************************************
222  * @brief Check whether RNG2 OSC calibration is on going.
223  *
224  * @retval : bool : true calibration is on going, false calibration is not started or done
225  ****************************************************************************************
226  */
228 
229 /**
230  ****************************************************************************************
231  * @brief Get RNG2 OSC calibration result.
232  * @param[in] wait_result : true will wait calibration done to get RNG2 OSC frequency
233  * @param[in] allow_cached : true will using previous RNG2 OSC calibration frequency
234  * @retval : uint32_t : RNG2 OSC frequency in HZ
235  ****************************************************************************************
236  */
237 uint32_t platform_rng2_calibration_get(bool wait_result, bool allow_cached);
238 
239 /**
240  ****************************************************************************************
241  * @brief Platform init function.
242  * @retval : void
243  ****************************************************************************************
244  */
245 void platform_init(void);
246 
247 /**
248  ****************************************************************************************
249  * @brief the first warm boot stage.
250  * @retval : void
251  ****************************************************************************************
252  */
253 void warm_boot_first(void);
254 
255  /**
256  ****************************************************************************************
257  * @brief the second warm boot stage..
258  * @retval : void
259  ****************************************************************************************
260  */
261 void warm_boot_second(void);
262 
263 /**
264  ****************************************************************************************
265  * @brief PMU init function.
266  * @param[in] clock_type : clock type to be configured.
267  * @retval : void
268  ****************************************************************************************
269  */
270 void system_pmu_init(mcu_clock_type_t clock_type);
271 
272 /**
273  ****************************************************************************************
274  * @brief PMU deinit function.
275  * @retval : void
276  ****************************************************************************************
277  */
278 void system_pmu_deinit(void);
279 
280 /**
281  ****************************************************************************************
282  * @brief Warm boot process.
283  * @retval : void
284  ****************************************************************************************
285  */
286 void warm_boot(void);
287 
288 /**
289  ****************************************************************************************
290  * @brief PMU calibration handler.
291  * @param[in] p_arg : no args.
292  * @retval : void
293  ****************************************************************************************
294  */
295 void pmu_calibration_handler(void* p_arg);
296 
297 /**
298  ****************************************************************************************
299  * @brief RTC calibration function.
300  * @retval : void
301  ****************************************************************************************
302  */
303 void rtc_calibration(void);
304 
305 /**
306  ****************************************************************************************
307  * @brief protection platform timeout through watchdog.
308  * @retval : hal status
309  ****************************************************************************************
310  */
312 
313 /**
314  ****************************************************************************************
315  * @brief protection platform timeout through watchdog.
316  * @retval : hal status
317  ****************************************************************************************
318  */
319 void platform_init_pop(void);
320 
321 /**
322  ****************************************************************************************
323  * @brief write flash QE
324  * @retval : hal status
325  ****************************************************************************************
326  */
328 
329 /**
330  ****************************************************************************************
331  * @brief During Flash erase/write operation, Disable external interrupts with a priority less
332  * than or equal to base_priority in the system.
333  * @param[in] base_priority: Base Priority value to set.
334  * @retval : hal status
335  ****************************************************************************************
336  */
337 hal_status_t platform_flash_protection(uint32_t base_priority);
338 
339 /**
340  ****************************************************************************************
341  * @brief protection interrupt handler during writing/erasing flash.
342  * @retval : hal status
343  ****************************************************************************************
344  */
346 
347 /**
348  ****************************************************************************************
349  * @brief protection interrupt handler during writing/erasing flash.
350  * @retval : hal status
351  ****************************************************************************************
352  */
354 
355 /**
356  ****************************************************************************************
357  * @brief set io_ldo_3p3_enable flag
358  * @retval : null
359  ****************************************************************************************
360  */
361 void set_io_ldo_use_3p3_v(bool flag);
362 
363 /** @} */
364 
365 #endif
366 
367 /** @} */
368 /** @} */
369 
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
RNG_OSC_CLK
@ RNG_OSC_CLK
RNG OSC CLOCK.
Definition: platform_sdk.h:79
sys_wakeup_osc_time_set
void sys_wakeup_osc_time_set(run_mode_t run_mode, uint16_t osc_us)
Set Time to wakeup oscillator before BLE Activity.
ble_sleep_algo_dur_set
void ble_sleep_algo_dur_set(run_mode_t run_mode, uint8_t dur_hus)
Set BLE Sleep Algorithm Duration.
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
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
run_mode_t
run_mode_t
system clock and run mode.
Definition: platform_sdk.h:61
ble_max_push_frame_time_set
void ble_max_push_frame_time_set(run_mode_t run_mode, uint8_t max_push_hus)
Set Maximum BLE Pushing Frame Time.
platform_init
void platform_init(void)
Platform init function.
set_io_ldo_use_3p3_v
void set_io_ldo_use_3p3_v(bool flag)
set io_ldo_3p3_enable flag
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
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
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.
platform_init_push
void platform_init_push(void)
protection platform timeout through watchdog.
rtc_calibration
void rtc_calibration(void)
RTC calibration function.
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.
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