1 /***************************************************************************//**
2 * \file cy_ble_clk.h
3 * \version 3.70
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.70</td>
54 *     <td>Added support for TRAVEO&trade; II Body Entry devices.<br>
55 *       Functionality added to address devices without buck controllers.</td>
56 *     <td>Code enhancement and support for new devices.</td>
57 *   </tr>
58 *   <tr>
59 *     <td>3.60</td>
60 *     <td>MISRA</td>
61 *     <td>Resolve MISRA 2012 standard defects.</td>
62 *   </tr>
63 *   <tr>
64 *     <td>3.50</td>
65 *     <td>Updated \ref Cy_BLE_EcoConfigure, \ref Cy_BLE_EcoReset functions
66 *         for PSoC 64 devices. Now the \ref Cy_BLE_EcoConfigure function can
67 *         return PRA driver status value for PSoC 64 devices.</td>
68 *     <td>The BLE ECO clock driver uses the PRA driver to change the frequency
69 *         value on the protected side. A BLE ECO clock driver function that
70 *         calls a PRA driver function will return the PRA error status code
71 *         if the called PRA function returns an error. In these cases,
72 *         refer to PRA return statuses. Refer to functions description for
73 *         details.</td>
74 *   </tr>
75 *   <tr>
76 *     <td>3.40.1</td>
77 *     <td>Minor documentation updates.</td>
78 *     <td>Documentation enhancement.</td>
79 *   </tr>
80 *   <tr>
81 *     <td>3.40</td>
82 *     <td>A new API function \ref Cy_BLE_EcoIsEnabled() is added.</td>
83 *     <td>API enhancement.</td>
84 *   </tr>
85 *   <tr>
86 *     <td>3.30</td>
87 *     <td>Updated the \ref Cy_BLE_EcoConfigure() to reuse the \ref Cy_SysClk_ClkPeriGetFrequency().</td>
88 *     <td>API enhancement.</td>
89 *   </tr>
90 *   <tr>
91 *     <td>3.20</td>
92 *     <td>Updated the Cy_BLE_EcoConfigure(): it stores the ECO frequency for possible frequency calculation by the Cy_SysClk_ClkHfGetFrequency().</td>
93 *     <td>API enhancement.</td>
94 *   </tr>
95 *   <tr>
96 *     <td>3.10</td>
97 *     <td>Updated the Cy_BLE_EcoConfigure() use case, when the voltageReg parameter is CY_BLE_ECO_VOLTAGE_REG_BLESSLDO
98 *         and the Buck core regulator is enabled.</td>
99 *     <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
100 *         the Buck core regulator had been enabled.</td>
101 *   </tr>
102 *   <tr>
103 *     <td>3.0</td>
104 *     <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>
105 *     <td>Independent usage of BLE ECO clock without BLE Middleware.</td>
106 *   </tr>
107 * </table>
108 *
109 * \defgroup group_ble_clk_functions Functions
110 * \defgroup group_ble_clk_data_type Enumerated Types
111 * \defgroup group_ble_clk_macros Macros
112 *
113 */
114 
115 #if !defined(CY_BLE_CLK_H)
116 #define CY_BLE_CLK_H
117 
118 #include "cy_device.h"
119 
120 #if defined (CY_IP_MXBLESS) && defined (CY_IP_MXS40IOSS)
121 
122 #include <stddef.h>
123 #include "cy_syslib.h"
124 
125 /* C binding of definitions if building with C++ compiler */
126 #ifdef __cplusplus
127 extern "C" {
128 #endif /* __cplusplus */
129 
130 
131 /*******************************************************************************
132 *       Macro definitions
133 *******************************************************************************/
134 
135 /**
136  * \addtogroup group_ble_clk_macros
137  * \{
138  */
139 /** Driver major version */
140 #define CY_BLE_CLK_DRV_VERSION_MAJOR    (3)
141 
142 /** Driver minor version */
143 #define CY_BLE_CLK_DRV_VERSION_MINOR    (70)
144 
145 /** Driver ID */
146 #define CY_BLE_CLK_ID                   (0x05UL << 18U)
147 /** \} */
148 
149 
150 /*******************************************************************************
151 *       Data Types
152 *******************************************************************************/
153 
154 /**
155  * \addtogroup group_ble_clk_data_type
156  * \{
157  */
158 /** BLE Radio ECO clock divider */
159 typedef enum
160 {
161     CY_BLE_MXD_RADIO_CLK_DIV_1  = 0U,
162     CY_BLE_MXD_RADIO_CLK_DIV_2  = 1U,
163     CY_BLE_MXD_RADIO_CLK_DIV_4  = 2U,
164     CY_BLE_MXD_RADIO_CLK_DIV_8  = 4U,
165     CY_BLE_MXD_RADIO_CLK_DIV_16 = 8U
166 } cy_en_ble_mxd_radio_clk_div_t;
167 
168 /** Sine wave buffer output capability select */
169 typedef enum
170 {
171     CY_BLE_MXD_RADIO_CLK_BUF_AMP_16M_SMALL = 0U,
172     CY_BLE_MXD_RADIO_CLK_BUF_AMP_16M_LARGE = 1U,
173     CY_BLE_MXD_RADIO_CLK_BUF_AMP_32M_SMALL = 2U,
174     CY_BLE_MXD_RADIO_CLK_BUF_AMP_32M_LARGE = 3U
175 } cy_en_ble_mxd_radio_clk_buf_amp_t;
176 
177 /** BLESS clock divider */
178 typedef enum
179 {
180     CY_BLE_BLESS_XTAL_CLK_DIV_1 = 0U,
181     CY_BLE_BLESS_XTAL_CLK_DIV_2 = 1U,
182     CY_BLE_BLESS_XTAL_CLK_DIV_4 = 2U,
183     CY_BLE_BLESS_XTAL_CLK_DIV_8 = 3U
184 }cy_en_ble_bless_xtal_clk_div_config_llclk_div_t;
185 
186 /** BLE ECO Clock Frequency. */
187 typedef enum
188 {
189     /** ECO Frequency of 16MHz */
190     CY_BLE_BLESS_ECO_FREQ_16MHZ,
191 
192     /** ECO Frequency of 32MHz */
193     CY_BLE_BLESS_ECO_FREQ_32MHZ
194 } cy_en_ble_eco_freq_t;
195 
196 /** BLE ECO System clock divider */
197 typedef enum
198 {
199     /** Link Layer clock divider = 1 */
200     CY_BLE_SYS_ECO_CLK_DIV_1 = 0x00U,
201 
202     /** Link Layer clock divider = 2 */
203     CY_BLE_SYS_ECO_CLK_DIV_2,
204 
205     /** Link Layer clock divider = 4 */
206     CY_BLE_SYS_ECO_CLK_DIV_4,
207 
208     /** Link Layer clock divider = 8 */
209     CY_BLE_SYS_ECO_CLK_DIV_8,
210 
211     /** Invalid Link Layer clock divider */
212     CY_BLE_SYS_ECO_CLK_DIV_INVALID
213 
214 } cy_en_ble_eco_sys_clk_div_t;
215 
216 /** BLE ECO Clock return value */
217 typedef enum
218 {
219     /** ECO started successfully */
220     CY_BLE_ECO_SUCCESS         = 0x00UL,
221 
222     /** Invalid input param values */
223     CY_BLE_ECO_BAD_PARAM       = CY_PDL_STATUS_ERROR | CY_BLE_CLK_ID | 0x0001UL,
224 
225     /** RCB is not available for Firmware control to restart ECO */
226     CY_BLE_ECO_RCB_CONTROL_LL  = CY_PDL_STATUS_ERROR | CY_BLE_CLK_ID | 0x0002UL,
227 
228     /** ECO already started */
229     CY_BLE_ECO_ALREADY_STARTED = CY_PDL_STATUS_ERROR | CY_BLE_CLK_ID | 0x0003UL,
230 
231     /** Hardware error */
232     CY_BLE_ECO_HARDWARE_ERROR  = CY_PDL_STATUS_ERROR | CY_BLE_CLK_ID | 0x0004UL,
233 
234 } cy_en_ble_eco_status_t;
235 
236 /** BLE Voltage regulator */
237 typedef enum
238 {
239     /** Use SIMO Buck or BLE LDO regulator depend on system usage */
240     CY_BLE_ECO_VOLTAGE_REG_AUTO,
241 
242     /** Use BLE LDO */
243     CY_BLE_ECO_VOLTAGE_REG_BLESSLDO
244 
245 } cy_en_ble_eco_voltage_reg_t;
246 /** \} */
247 
248 
249 /*******************************************************************************
250 *       Configuration Structures
251 *******************************************************************************/
252 
253 /** \cond INTERNAL */
254 /** BLE ECO configuration structures */
255 typedef struct
256 {
257     /**
258      *  ECO crystal startup time in multiple of 31.25us (startup_time_from_user min - 31.25us)
259      *  ecoXtalStartUpTime = startup_time_from_user/31.25
260      */
261     uint8_t                           ecoXtalStartUpTime;
262 
263     /**
264      *  ECO crystal load capacitance - In multiple of 0.075pF (pF_from_user min - 7.5pF, pF_from_user max - 26.625pF)
265      *  loadcap = ((pF_from_user - 7.5)/0.075)
266      */
267     uint8_t                           loadCap;
268 
269     /** ECO Frequency. */
270     cy_en_ble_eco_freq_t              ecoFreq;
271 
272     /** System divider for ECO clock. */
273     cy_en_ble_eco_sys_clk_div_t       ecoSysDiv;
274 
275 } cy_stc_ble_eco_config_t;
276 
277 #if (defined(CY_DEVICE_SECURE))
278 /** PRA structure for Cy_BLE_EcoConfigure function parameters */
279 typedef struct
280 {
281     cy_en_ble_eco_freq_t freq;
282     cy_en_ble_eco_sys_clk_div_t sysClkDiv;
283     uint32_t cLoad;
284     uint32_t xtalStartUpTime;
285     cy_en_ble_eco_voltage_reg_t voltageReg;
286 } cy_stc_pra_ble_eco_config_t;
287 #endif /* (defined(CY_DEVICE_SECURE)) */
288 
289 /** \endcond */
290 
291 
292 /*******************************************************************************
293 *       Function Prototypes
294 *******************************************************************************/
295 
296 /**
297  * \addtogroup group_ble_clk_functions
298  * \{
299  */
300 cy_en_ble_eco_status_t Cy_BLE_EcoConfigure(cy_en_ble_eco_freq_t freq,
301                                     cy_en_ble_eco_sys_clk_div_t sysClkDiv,
302                                                        uint32_t cLoad,
303                                                        uint32_t xtalStartUpTime,
304                                     cy_en_ble_eco_voltage_reg_t voltageReg);
305 void Cy_BLE_EcoReset(void);
306 __STATIC_INLINE bool Cy_BLE_EcoIsEnabled(void);
307 
308 
309 /*******************************************************************************
310 * Function Name: Cy_BLE_EcoIsEnabled
311 ****************************************************************************//**
312 *
313 *  Reports the Enabled/Disabled BLE ECO status.
314 *
315 *  \return Boolean status of BLE ECO: true - Enabled, false - Disabled.
316 *
317 *******************************************************************************/
Cy_BLE_EcoIsEnabled(void)318 __STATIC_INLINE bool Cy_BLE_EcoIsEnabled(void)
319 {
320     return (((BLE_BLESS_MT_CFG & BLE_BLESS_MT_CFG_ENABLE_BLERD_Msk) != 0u) &&
321             ((BLE_BLESS_MT_STATUS & BLE_BLESS_MT_STATUS_BLESS_STATE_Msk) != 0u));
322 }
323 /** \} */
324 
325 /** \cond INTERNAL */
326 cy_en_ble_eco_status_t Cy_BLE_EcoStart(const cy_stc_ble_eco_config_t *config);
327 void Cy_BLE_EcoStop(void);
328 /** \endcond */
329 
330 
331 /*******************************************************************************
332 *       Private Function Prototypes
333 *******************************************************************************/
334 
335 /** \cond INTERNAL */
336 void Cy_BLE_HAL_Init(void);
337 
338 
339 /*******************************************************************************
340 *       Backwards compatibility macros
341 *******************************************************************************/
342 
343 #define cy_stc_ble_bless_eco_cfg_params_t   cy_stc_ble_eco_config_t
344 #define cy_en_ble_bless_sys_eco_clk_div_t   cy_en_ble_eco_sys_clk_div_t
345 #define cy_en_ble_bless_eco_freq_t          cy_en_ble_eco_freq_t
346 /** \endcond */
347 
348 
349 #ifdef __cplusplus
350 }
351 #endif /* __cplusplus */
352 #endif /* defined(CY_IP_MXBLESS) */
353 #endif /* CY_BLE_CLK_H */
354 
355 /** \} group_ble_clk */
356 
357 /* [] END OF FILE */
358