1 /***************************************************************************//**
2 * \file cy_ble_clk.h
3 * \version 3.60
4 *
5 * The header file of the BLE ECO clock driver.
6 *
7 ********************************************************************************
8 * \copyright
9 * Copyright 2017-2020 Cypress Semiconductor Corporation
10 * SPDX-License-Identifier: Apache-2.0
11 *
12 * Licensed under the Apache License, Version 2.0 (the "License");
13 * you may not use this file except in compliance with the License.
14 * You may obtain a copy of the License at
15 *
16 * http://www.apache.org/licenses/LICENSE-2.0
17 *
18 * Unless required by applicable law or agreed to in writing, software
19 * distributed under the License is distributed on an "AS IS" BASIS,
20 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21 * See the License for the specific language governing permissions and
22 * limitations under the License.
23 *******************************************************************************/
24
25 /**
26 * \addtogroup group_ble_clk
27 * \{
28 * This driver provides an API to manage the BLE ECO clock block.
29 *
30 * The functions and other declarations used in this driver are in cy_ble_clk.h.
31 * You can include cy_pdl.h to get access to all functions
32 * and declarations in the PDL.
33 *
34 * The BLE ECO clock is a high-accuracy high-frequency clock that feeds the
35 * link-layer controller and the radio Phy.
36 *
37 * This clock is also an input to the system resources subsystem as an
38 * alternative high-frequency clock source (ALTHF).
39 *
40 * \section group_ble_configuration_considerations Configuration Considerations
41 * To configure the BLE ECO clock, call Cy_BLE_EcoConfigure().
42 *
43 * The following code shows how to configure the BLE ECO clock:
44 * \snippet bleclk/snippet/main.c BLE ECO clock API: Cy_BLE_EcoConfigure()
45 *
46 * \section group_ble_clk_more_information More Information
47 * See the BLE chapter of the device technical reference manual (TRM).
48 *
49 * \section group_ble_clk_changelog Changelog
50 * <table class="doxtable">
51 * <tr><th>Version</th><th>Changes</th><th>Reason of Change</th></tr>
52 * <tr>
53 * <td>3.60</td>
54 * <td>MISRA</td>
55 * <td>Resolve MISRA 2012 standard defects.</td>
56 * </tr>
57 * <tr>
58 * <td>3.50</td>
59 * <td>Updated \ref Cy_BLE_EcoConfigure, \ref Cy_BLE_EcoReset functions
60 * for PSoC 64 devices. Now the \ref Cy_BLE_EcoConfigure function can
61 * return PRA driver status value for PSoC 64 devices.</td>
62 * <td>The BLE ECO clock driver uses the PRA driver to change the frequency
63 * value on the protected side. A BLE ECO clock driver function that
64 * calls a PRA driver function will return the PRA error status code
65 * if the called PRA function returns an error. In these cases,
66 * refer to PRA return statuses. Refer to functions description for
67 * details.</td>
68 * </tr>
69 * <tr>
70 * <td>3.40.1</td>
71 * <td>Minor documentation updates.</td>
72 * <td>Documentation enhancement.</td>
73 * </tr>
74 * <tr>
75 * <td>3.40</td>
76 * <td>A new API function \ref Cy_BLE_EcoIsEnabled() is added.</td>
77 * <td>API enhancement.</td>
78 * </tr>
79 * <tr>
80 * <td>3.30</td>
81 * <td>Updated the \ref Cy_BLE_EcoConfigure() to reuse the \ref Cy_SysClk_ClkPeriGetFrequency().</td>
82 * <td>API enhancement.</td>
83 * </tr>
84 * <tr>
85 * <td>3.20</td>
86 * <td>Updated the Cy_BLE_EcoConfigure(): it stores the ECO frequency for possible frequency calculation by the Cy_SysClk_ClkHfGetFrequency().</td>
87 * <td>API enhancement.</td>
88 * </tr>
89 * <tr>
90 * <td>3.10</td>
91 * <td>Updated the Cy_BLE_EcoConfigure() use case, when the voltageReg parameter is CY_BLE_ECO_VOLTAGE_REG_BLESSLDO
92 * and the Buck core regulator is enabled.</td>
93 * <td>Defect fixing: Before, when the Cy_BLE_EcoConfigure() function included the BLE LDO regulator option, the function returned CY_BLE_ECO_HARDWARE_ERROR if
94 * the Buck core regulator had been enabled.</td>
95 * </tr>
96 * <tr>
97 * <td>3.0</td>
98 * <td>The initial version. \n The functionality of the BLE ECO clock is migrated from the BLE Middleware to the separated driver (ble_clk).</td>
99 * <td>Independent usage of BLE ECO clock without BLE Middleware.</td>
100 * </tr>
101 * </table>
102 *
103 * \defgroup group_ble_clk_functions Functions
104 * \defgroup group_ble_clk_data_type Enumerated Types
105 * \defgroup group_ble_clk_macros Macros
106 *
107 */
108
109 #if !defined(CY_BLE_CLK_H)
110 #define CY_BLE_CLK_H
111
112 #include "cy_device.h"
113
114 #if defined (CY_IP_MXBLESS) && defined (CY_IP_MXS40IOSS)
115
116 #include <stddef.h>
117 #include "cy_syslib.h"
118
119 /* C binding of definitions if building with C++ compiler */
120 #ifdef __cplusplus
121 extern "C" {
122 #endif /* __cplusplus */
123
124
125 /*******************************************************************************
126 * Macro definitions
127 *******************************************************************************/
128
129 /**
130 * \addtogroup group_ble_clk_macros
131 * \{
132 */
133 /** Driver major version */
134 #define CY_BLE_CLK_DRV_VERSION_MAJOR (3)
135
136 /** Driver minor version */
137 #define CY_BLE_CLK_DRV_VERSION_MINOR (60)
138
139 /** Driver ID */
140 #define CY_BLE_CLK_ID (0x05UL << 18U)
141 /** \} */
142
143
144 /*******************************************************************************
145 * Data Types
146 *******************************************************************************/
147
148 /**
149 * \addtogroup group_ble_clk_data_type
150 * \{
151 */
152 /** BLE Radio ECO clock divider */
153 typedef enum
154 {
155 CY_BLE_MXD_RADIO_CLK_DIV_1 = 0U,
156 CY_BLE_MXD_RADIO_CLK_DIV_2 = 1U,
157 CY_BLE_MXD_RADIO_CLK_DIV_4 = 2U,
158 CY_BLE_MXD_RADIO_CLK_DIV_8 = 4U,
159 CY_BLE_MXD_RADIO_CLK_DIV_16 = 8U
160 } cy_en_ble_mxd_radio_clk_div_t;
161
162 /** Sine wave buffer output capability select */
163 typedef enum
164 {
165 CY_BLE_MXD_RADIO_CLK_BUF_AMP_16M_SMALL = 0U,
166 CY_BLE_MXD_RADIO_CLK_BUF_AMP_16M_LARGE = 1U,
167 CY_BLE_MXD_RADIO_CLK_BUF_AMP_32M_SMALL = 2U,
168 CY_BLE_MXD_RADIO_CLK_BUF_AMP_32M_LARGE = 3U
169 } cy_en_ble_mxd_radio_clk_buf_amp_t;
170
171 /** BLESS clock divider */
172 typedef enum
173 {
174 CY_BLE_BLESS_XTAL_CLK_DIV_1 = 0U,
175 CY_BLE_BLESS_XTAL_CLK_DIV_2 = 1U,
176 CY_BLE_BLESS_XTAL_CLK_DIV_4 = 2U,
177 CY_BLE_BLESS_XTAL_CLK_DIV_8 = 3U
178 }cy_en_ble_bless_xtal_clk_div_config_llclk_div_t;
179
180 /** BLE ECO Clock Frequency. */
181 typedef enum
182 {
183 /** ECO Frequency of 16MHz */
184 CY_BLE_BLESS_ECO_FREQ_16MHZ,
185
186 /** ECO Frequency of 32MHz */
187 CY_BLE_BLESS_ECO_FREQ_32MHZ
188 } cy_en_ble_eco_freq_t;
189
190 /** BLE ECO System clock divider */
191 typedef enum
192 {
193 /** Link Layer clock divider = 1 */
194 CY_BLE_SYS_ECO_CLK_DIV_1 = 0x00U,
195
196 /** Link Layer clock divider = 2 */
197 CY_BLE_SYS_ECO_CLK_DIV_2,
198
199 /** Link Layer clock divider = 4 */
200 CY_BLE_SYS_ECO_CLK_DIV_4,
201
202 /** Link Layer clock divider = 8 */
203 CY_BLE_SYS_ECO_CLK_DIV_8,
204
205 /** Invalid Link Layer clock divider */
206 CY_BLE_SYS_ECO_CLK_DIV_INVALID
207
208 } cy_en_ble_eco_sys_clk_div_t;
209
210 /** BLE ECO Clock return value */
211 typedef enum
212 {
213 /** ECO started successfully */
214 CY_BLE_ECO_SUCCESS = 0x00UL,
215
216 /** Invalid input param values */
217 CY_BLE_ECO_BAD_PARAM = CY_PDL_STATUS_ERROR | CY_BLE_CLK_ID | 0x0001UL,
218
219 /** RCB is not available for Firmware control to restart ECO */
220 CY_BLE_ECO_RCB_CONTROL_LL = CY_PDL_STATUS_ERROR | CY_BLE_CLK_ID | 0x0002UL,
221
222 /** ECO already started */
223 CY_BLE_ECO_ALREADY_STARTED = CY_PDL_STATUS_ERROR | CY_BLE_CLK_ID | 0x0003UL,
224
225 /** Hardware error */
226 CY_BLE_ECO_HARDWARE_ERROR = CY_PDL_STATUS_ERROR | CY_BLE_CLK_ID | 0x0004UL,
227
228 } cy_en_ble_eco_status_t;
229
230 /** BLE Voltage regulator */
231 typedef enum
232 {
233 /** Use SIMO Buck or BLE LDO regulator depend on system usage */
234 CY_BLE_ECO_VOLTAGE_REG_AUTO,
235
236 /** Use BLE LDO */
237 CY_BLE_ECO_VOLTAGE_REG_BLESSLDO
238
239 } cy_en_ble_eco_voltage_reg_t;
240 /** \} */
241
242
243 /*******************************************************************************
244 * Configuration Structures
245 *******************************************************************************/
246
247 /** \cond INTERNAL */
248 /** BLE ECO configuration structures */
249 typedef struct
250 {
251 /**
252 * ECO crystal startup time in multiple of 31.25us (startup_time_from_user min - 31.25us)
253 * ecoXtalStartUpTime = startup_time_from_user/31.25
254 */
255 uint8_t ecoXtalStartUpTime;
256
257 /**
258 * ECO crystal load capacitance - In multiple of 0.075pF (pF_from_user min - 7.5pF, pF_from_user max - 26.625pF)
259 * loadcap = ((pF_from_user - 7.5)/0.075)
260 */
261 uint8_t loadCap;
262
263 /** ECO Frequency. */
264 cy_en_ble_eco_freq_t ecoFreq;
265
266 /** System divider for ECO clock. */
267 cy_en_ble_eco_sys_clk_div_t ecoSysDiv;
268
269 } cy_stc_ble_eco_config_t;
270
271 #if (defined(CY_DEVICE_SECURE))
272 /** PRA structure for Cy_BLE_EcoConfigure function parameters */
273 typedef struct
274 {
275 cy_en_ble_eco_freq_t freq;
276 cy_en_ble_eco_sys_clk_div_t sysClkDiv;
277 uint32_t cLoad;
278 uint32_t xtalStartUpTime;
279 cy_en_ble_eco_voltage_reg_t voltageReg;
280 } cy_stc_pra_ble_eco_config_t;
281 #endif /* (defined(CY_DEVICE_SECURE)) */
282
283 /** \endcond */
284
285
286 /*******************************************************************************
287 * Function Prototypes
288 *******************************************************************************/
289
290 /**
291 * \addtogroup group_ble_clk_functions
292 * \{
293 */
294 cy_en_ble_eco_status_t Cy_BLE_EcoConfigure(cy_en_ble_eco_freq_t freq,
295 cy_en_ble_eco_sys_clk_div_t sysClkDiv,
296 uint32_t cLoad,
297 uint32_t xtalStartUpTime,
298 cy_en_ble_eco_voltage_reg_t voltageReg);
299 void Cy_BLE_EcoReset(void);
300 __STATIC_INLINE bool Cy_BLE_EcoIsEnabled(void);
301
302
303 /*******************************************************************************
304 * Function Name: Cy_BLE_EcoIsEnabled
305 ****************************************************************************//**
306 *
307 * Reports the Enabled/Disabled BLE ECO status.
308 *
309 * \return Boolean status of BLE ECO: true - Enabled, false - Disabled.
310 *
311 *******************************************************************************/
Cy_BLE_EcoIsEnabled(void)312 __STATIC_INLINE bool Cy_BLE_EcoIsEnabled(void)
313 {
314 return (((BLE_BLESS_MT_CFG & BLE_BLESS_MT_CFG_ENABLE_BLERD_Msk) != 0u) &&
315 ((BLE_BLESS_MT_STATUS & BLE_BLESS_MT_STATUS_BLESS_STATE_Msk) != 0u));
316 }
317 /** \} */
318
319 /** \cond INTERNAL */
320 cy_en_ble_eco_status_t Cy_BLE_EcoStart(const cy_stc_ble_eco_config_t *config);
321 void Cy_BLE_EcoStop(void);
322 /** \endcond */
323
324
325 /*******************************************************************************
326 * Private Function Prototypes
327 *******************************************************************************/
328
329 /** \cond INTERNAL */
330 void Cy_BLE_HAL_Init(void);
331
332
333 /*******************************************************************************
334 * Backwards compatibility macros
335 *******************************************************************************/
336
337 #define cy_stc_ble_bless_eco_cfg_params_t cy_stc_ble_eco_config_t
338 #define cy_en_ble_bless_sys_eco_clk_div_t cy_en_ble_eco_sys_clk_div_t
339 #define cy_en_ble_bless_eco_freq_t cy_en_ble_eco_freq_t
340 /** \endcond */
341
342
343 #ifdef __cplusplus
344 }
345 #endif /* __cplusplus */
346 #endif /* defined(CY_IP_MXBLESS) */
347 #endif /* CY_BLE_CLK_H */
348
349 /** \} group_ble_clk */
350
351 /* [] END OF FILE */
352
