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_gr5405.h"
54 #include "hal_def.h"
55 #include "ll_xqspi.h"
56 
57 /** @} */
58 
59 /**@addtogroup PlAT_SDK_ENUM Enumerations
60  * @{ */
61 
62 /**@brief system clock and run mode. */
63 typedef enum
64 {
65  XIP_64M = 0, /**< XIP 64M. */
66  XIP_48M, /**< XIP 48M. */
67  XIP_XO16M, /**< XIP XO 16M. */
68  XIP_24M, /**< XIP 24M. */
69  XIP_16M, /**< XIP 16M. */
70  XIP_32M, /**< XIP 32M. */
71  MIRROR_64M, /**< MIRROR 64M. */
72  MIRROR_48M, /**< MIRROR 48M. */
73  MIRROR_XO16M, /**< MIRROR X) 16M. */
74  MIRROR_24M, /**< MIRROR 24M. */
75  MIRROR_16M, /**< MIRROR 16M. */
76  MIRROR_32M, /**< MIRROR 32M. */
77 } table_idx_t;
78 
79 /**@brief slow clock type. */
80 typedef enum
81 {
82  RC_OSC_CLK = 0, /**< RC OSC CLOCK. */
83  RTC_OSC_CLK, /**< RTC OSC CLOCK. */
85 
86 
87 /**@brief memory power setting mode. */
88 typedef enum
89 {
90  MEM_POWER_FULL_MODE = 0, /**< Full mode. */
91  MEM_POWER_AUTO_MODE, /**< Auto mode. */
92 } mem_power_t;
93 
94  /**@brief system power mode. */
95  typedef enum
96  {
97  DCDC_MODE = 0, /**< Start with DCDC only. */
98  SYSLDO_MODE = 1, /**< Start with SYSLDO only. */
99  DCDC_MODE_2 = 2, /**< Start with SYSLDO and work with DCDC. */
100  } sys_power_t;
101 
102  /** @} */
103 
104 /** @addtogroup PLAT_SDK_FUNCTIONS Functions
105  * @{ */
106 
107 /**@brief clock calibration notify callback. */
108 typedef void (*clock_calib_notify_cb_t)(float SlowClockFreq);
109 
110 /**
111  ****************************************************************************************
112  * @brief platform sdk init function.
113  * @retval : void
114  ****************************************************************************************
115  */
116 void platform_sdk_init(void);
117 
118 /**
119  ****************************************************************************************
120  * @brief Set the memory power management mode, which can be automatic mode or full power on mode.
121  * @param[in] mem_pwr_mode : MEM_POWER_FULL_MODE or MEM_POWER_AUTO_MODE.
122  * @retval : void
123  ****************************************************************************************
124  */
126 
127 /**
128  ****************************************************************************************
129  * @brief Control the memory power supply by specifying start address and length.
130  * @param[in] start_addr : the start address of memory that user want to config
131  * @param[in] size : the size of memory that user want to config
132  * @retval : void
133  ****************************************************************************************
134  */
135 void mem_pwr_mgmt_mode_set_from(uint32_t start_addr, uint32_t size);
136 
137 /**
138  ****************************************************************************************
139  * @brief Enable patch function.
140  * @param[in] table_idx : Start Index Number.
141  * @param[in] dur_offset : duration setting.
142  * @param[in] ext_offset : ext wakeup setting.
143  * @param[in] osc_offset : pre-wakeup setting.
144  * @retval : void
145  ****************************************************************************************
146  */
147 void system_lp_table_update_twval(table_idx_t table_idx, int16_t dur_offset, int16_t ext_offset, int16_t osc_offset);
148 
149 /**
150  ****************************************************************************************
151  * @brief Platform low power clock init function.
152  * @param[in] sys_clock: System clock.
153  * @param[in] slow_clock: External RTC setting or internal RNG_OSC/RC_32K setting.
154  * @param[in] accuracy : Low speed clock accuracy.
155  * @param[in] xo_offset : Clock calibration parameter.
156  * @retval : void
157  ****************************************************************************************
158  */
159 void platform_clock_init(mcu_clock_type_t sys_clock, slow_clock_type_t slow_clock, uint16_t accuracy, uint16_t xo_offset);
160 
161 /**
162  ****************************************************************************************
163  * @brief Platform rc calibration function.
164  * @retval : void
165  ****************************************************************************************
166  */
168 
169 /**
170  ****************************************************************************************
171  * @brief Power Management warm boot.
172  *
173  * @retval : void
174  ****************************************************************************************
175  */
177 
178 /**
179  ****************************************************************************************
180  * @brief Handle Clock calibration interrupt request.
181  * @retval : void
182  ****************************************************************************************
183  */
185 
186 /**
187  ****************************************************************************************
188  * @brief Check whether the clock calibration is completed.
189  * If it is not completed, the chip is not allowed to enter sleep.
190  * @retval :: true: clock calibration is completed.
191  :: false: clock calibration is not completed.
192  ****************************************************************************************
193  */
195 
196 /**
197  ****************************************************************************************
198  * @brief update comm wakeup timing settings according to lf clock
199  * @retval : void
200  ****************************************************************************************
201  */
203 
204 /**
205  ****************************************************************************************
206  * @brief Platform init function.
207  * @retval : void
208  ****************************************************************************************
209  */
210 void platform_init(void);
211 
212 /**
213  ****************************************************************************************
214  * @brief System power starup mode.
215  * @param[in] sys_power : System power up mode to be configured.
216  * @retval : void
217  ****************************************************************************************
218  */
220 
221 /**
222  ****************************************************************************************
223  * @brief PMU init function.
224  * @param[in] clock_type : clock type to be configured.
225  * @retval : void
226  ****************************************************************************************
227  */
228 void system_pmu_init(mcu_clock_type_t clock_type);
229 
230 /**
231  ****************************************************************************************
232  * @brief PMU deinit function.
233  * @retval : void
234  ****************************************************************************************
235  */
238 void system_pmu_deinit(void);
239 
240 /**
241  ****************************************************************************************
242  * @brief the first warm boot stage.
243  * @retval : void
244  ****************************************************************************************
245  */
246 void warm_boot_first(void);
247 
248  /**
249  ****************************************************************************************
250  * @brief the second warm boot stage..
251  * @retval : void
252  ****************************************************************************************
253  */
254 void warm_boot_second(void);
255 
256 /**
257  ****************************************************************************************
258  * @brief Warm boot process.
259  * @retval : void
260  ****************************************************************************************
261  */
262 void warm_boot(void);
263 
264 /**
265  ****************************************************************************************
266  * @brief PMU calibration handler.
267  * @param[in] p_arg : no args.
268  * @retval : void
269  ****************************************************************************************
270  */
271 void pmu_calibration_handler(void* p_arg);
272 
273 /**
274  ****************************************************************************************
275  * @brief If the last PMU calibration failed, do the calibration again
276  * @retval : void
277  ****************************************************************************************
278  */
280 
281 /**
282  ****************************************************************************************
283  * @brief Register the clock calibration completion callback.
284  * @param[in] calib_notify_cb : Calibration completion callback.
285  *
286  * @retval ::SDK_SUCCESS: Register callback Successfully.
287  * @retval ::SDK_ERR_POINTER_NULL: calib_notify_cb is null pointer.
288  * @retval ::SDK_ERR_LIST_FULL: Operation is failed, the clock calibration completion callback is full.
289  ****************************************************************************************
290  */
292 
293 /**
294  ****************************************************************************************
295  * @brief Unregister the clock calibration completion callback.
296  * @param[in] calib_notify_cb : Calibration completion callback.
297  *
298  * @retval ::SDK_SUCCESS: Unregister callback Successfully.
299  * @retval ::SDK_ERR_POINTER_NULL: calib_notify_cb is null pointer.
300  * @retval ::SDK_ERR_LIST_ITEM_NOT_FOUND: Operation is failed, the clock calibration completion has not been registered.
301  ****************************************************************************************
302  */
304 
305 /**
306  ****************************************************************************************
307  * @brief stop calibration.
308  * @retval : void
309  ****************************************************************************************
310  */
312 
313 /**
314  ****************************************************************************************
315  * @brief get ddvs ringo count
316  * @retval : ringo count
317  ****************************************************************************************
318  */
319 uint32_t sys_pmu_ddvs_ringo_get(void);
320 
321 /**
322  ****************************************************************************************
323  * @brief set dcdc sysldo & digocre
324  * @retval : void
325  ****************************************************************************************
326  */
328 
329 /**
330  ****************************************************************************************
331  * @brief adjust digcore with ddvs
332  * @param[in] clock_type : clock type
333  ****************************************************************************************
334  */
335 void sys_pmu_ddvs_dcore_adjust(uint8_t clock_type);
336 /**
337  ****************************************************************************************
338  * @brief adjust digcore with ddvs
339  * @retval bool
340  ****************************************************************************************
341  */
343 
344 /**
345  ****************************************************************************************
346  * @brief Set the protected interrupt level. Interrupts with a lower priority group
347  * than the protected interrupt will be blocked in pmu calibration.
348  * The default protected interrupt level is BLE_IRQn.
349  * @retval void
350  ****************************************************************************************
351  */
352 void sys_set_protect_irq(IRQn_Type IRQn);
353 
354 /**
355  ****************************************************************************************
356  * @brief Get the protected interrupt level
357  * @retval IRQn_Type
358  ****************************************************************************************
359  */
360 IRQn_Type sys_get_protect_irq(void);
361 
362 /** @} */
363 
364 #endif
365 
366 /** @} */
sys_set_protect_irq
void sys_set_protect_irq(IRQn_Type IRQn)
Set the protected interrupt level. Interrupts with a lower priority group than the protected interrup...
sys_power_t
sys_power_t
system power mode.
Definition: platform_sdk.h:96
system_pmu_calibration_stop
void system_pmu_calibration_stop(void)
stop calibration.
XIP_16M
@ XIP_16M
Definition: platform_sdk.h:69
clock_calib_notify_cb_t
void(* clock_calib_notify_cb_t)(float SlowClockFreq)
clock calibration notify callback.
Definition: platform_sdk.h:108
sys_get_protect_irq
IRQn_Type sys_get_protect_irq(void)
Get the protected interrupt level.
ll_xqspi.h
Header file containing functions prototypes of XQSPI LL library.
platform_rc_calibration
void platform_rc_calibration(void)
Platform rc calibration function.
clock_calib_notify_register
uint16_t clock_calib_notify_register(clock_calib_notify_cb_t calib_notify_cb)
Register the clock calibration completion callback.
sys_dcdc_sysldo_dcore_init
void sys_dcdc_sysldo_dcore_init(void)
set dcdc sysldo & digocre
system_power_mode
void system_power_mode(sys_power_t sys_power)
System power starup mode.
MIRROR_32M
@ MIRROR_32M
Definition: platform_sdk.h:76
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.
slow_clock_type_t
slow_clock_type_t
slow clock type.
Definition: platform_sdk.h:81
pwr_mgmt_update_comm_wkup_timing_param
void pwr_mgmt_update_comm_wkup_timing_param(void)
update comm wakeup timing settings according to lf clock
MIRROR_24M
@ MIRROR_24M
Definition: platform_sdk.h:74
tx_power_normal_pmu_apply
void tx_power_normal_pmu_apply(void)
MEM_POWER_AUTO_MODE
@ MEM_POWER_AUTO_MODE
Definition: platform_sdk.h:91
sys_pmu_is_ss_chip
bool sys_pmu_is_ss_chip(void)
adjust digcore with ddvs
XIP_24M
@ XIP_24M
Definition: platform_sdk.h:68
DCDC_MODE
@ DCDC_MODE
Definition: platform_sdk.h:97
platform_sdk_init
void platform_sdk_init(void)
platform sdk init function.
mem_power_t
mem_power_t
memory power setting mode.
Definition: platform_sdk.h:89
XIP_32M
@ XIP_32M
Definition: platform_sdk.h:70
RTC_OSC_CLK
@ RTC_OSC_CLK
Definition: platform_sdk.h:83
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.
MIRROR_64M
@ MIRROR_64M
Definition: platform_sdk.h:71
SYSLDO_MODE
@ SYSLDO_MODE
Definition: platform_sdk.h:98
MIRROR_16M
@ MIRROR_16M
Definition: platform_sdk.h:75
table_idx_t
table_idx_t
system clock and run mode.
Definition: platform_sdk.h:64
platform_init
void platform_init(void)
Platform init function.
platform_clock_init
void platform_clock_init(mcu_clock_type_t sys_clock, slow_clock_type_t slow_clock, uint16_t accuracy, uint16_t xo_offset)
Platform low power clock init function.
system_pmu_init
void system_pmu_init(mcu_clock_type_t clock_type)
PMU init function.
tx_power_15dbm_pmu_apply
void tx_power_15dbm_pmu_apply(void)
PMU deinit function.
warm_boot_second
void warm_boot_second(void)
the second warm boot stage..
clock_calibration_is_done
bool clock_calibration_is_done(void)
Check whether the clock calibration is completed. If it is not completed, the chip is not allowed to ...
clock_calibration_irq_handler
void clock_calibration_irq_handler(void)
Handle Clock calibration interrupt request.
clock_calib_notify_unregister
uint16_t clock_calib_notify_unregister(clock_calib_notify_cb_t calib_notify_cb)
Unregister the clock calibration completion callback.
hal_def.h
This file contains HAL common definitions, enumeration, macros and structures definitions.
XIP_48M
@ XIP_48M
Definition: platform_sdk.h:66
MIRROR_48M
@ MIRROR_48M
Definition: platform_sdk.h:72
DCDC_MODE_2
@ DCDC_MODE_2
Definition: platform_sdk.h:99
MEM_POWER_FULL_MODE
@ MEM_POWER_FULL_MODE
Definition: platform_sdk.h:90
XIP_64M
@ XIP_64M
Definition: platform_sdk.h:65
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.
warm_boot
void warm_boot(void)
Warm boot process.
pmu_calibration_check_and_retry
void pmu_calibration_check_and_retry(void)
If the last PMU calibration failed, do the calibration again.
system_pmu_deinit
void system_pmu_deinit(void)
MIRROR_XO16M
@ MIRROR_XO16M
Definition: platform_sdk.h:73
sys_pmu_ddvs_dcore_adjust
void sys_pmu_ddvs_dcore_adjust(uint8_t clock_type)
adjust digcore with ddvs
RC_OSC_CLK
@ RC_OSC_CLK
Definition: platform_sdk.h:82
sys_pmu_ddvs_ringo_get
uint32_t sys_pmu_ddvs_ringo_get(void)
get ddvs ringo count
system_lp_table_update_twval
void system_lp_table_update_twval(table_idx_t table_idx, int16_t dur_offset, int16_t ext_offset, int16_t osc_offset)
Enable patch function.
XIP_XO16M
@ XIP_XO16M
Definition: platform_sdk.h:67
pmu_calibration_handler
void pmu_calibration_handler(void *p_arg)
PMU calibration handler.