CAT2 Peripheral Driver Library
Functions
Functions
SysClk (System Clock) » External Crystal Oscillator (ECO)

Functions

cy_en_sysclk_status_t Cy_SysClk_EcoConfigure (uint32_t freq, uint32_t cLoad, uint32_t esr, uint32_t driveLevel)
 Configures the external crystal oscillator (ECO) trim bits based on crystal characteristics. More...
 
cy_en_sysclk_status_t Cy_SysClk_EcoEnable (uint32_t timeoutUs)
 Enables the external crystal oscillator (ECO). More...
 
uint32_t Cy_SysClk_EcoGetFrequency (void)
 Returns the frequency of the external crystal oscillator (ECO). More...
 
__STATIC_INLINE bool Cy_SysClk_EcoIsEnabled (void)
 Returns the ECO enable/disable state. More...
 
__STATIC_INLINE void Cy_SysClk_EcoDisable (void)
 Disables the external crystal oscillator (ECO). More...
 
__STATIC_INLINE cy_en_sysclk_eco_stat_t Cy_SysClk_EcoGetStatus (void)
 Reports the current status of the external crystal oscillator (ECO). More...
 

Detailed Description

Function Documentation

◆ Cy_SysClk_EcoConfigure()

cy_en_sysclk_status_t Cy_SysClk_EcoConfigure ( uint32_t  freq,
uint32_t  cLoad,
uint32_t  esr,
uint32_t  driveLevel 
)

Configures the external crystal oscillator (ECO) trim bits based on crystal characteristics.

This function should be called only when the ECO is disabled.

Note
Not applicable for PSOC4 HVMS/PA.
Parameters
freqOperating frequency of the crystal in Hz. Valid range: 4000000...33330000 (4..33.33 MHz).
cLoadCrystal load capacitance in pF. Valid range: 1...100.
esrEffective series resistance of the crystal in ohms. Valid range: 1...1000.
driveLevelCrystal drive level in uW. Valid range: 1...2000.
Returns
Error / status code cy_en_sysclk_status_t :
CY_SYSCLK_SUCCESS - ECO configuration completed successfully
CY_SYSCLK_BAD_PARAM - One or more invalid parameters
CY_SYSCLK_INVALID_STATE - ECO already enabled
Note
The following calculations are implemented in integer 32-bitwise math:
*   freqKhz = freq / 1000
*   maxAmpl = sqrt(drivelevel / 2 / esr) / 3.14 / freqKhz / cLoad
*   ampSect = INT(5 * 4 * 3.14^2 * freqKhz^2 * cLoad^2 * 4 * esr / 1000000000 / 1000000 / 4.5)
*
*   As a result of the above calculations, maxAmpl must be >= 0.5, and the
*   number of amplifier sections must be <= 3, otherwise this function returns with
*   a parameter error.
*
*   atrim = maxAmpl < 0.6 ? 0 :
*           maxAmpl < 0.7 ? 1 :
*           maxAmpl < 0.8 ? 2 :
*           maxAmpl < 0.9 ? 3 :
*           maxAmpl < 1.025 ? 4 :
*           maxAmpl < 1.150 ? 5 :
*           maxAmpl < 1.275 ? 6 : 7

*   wdtrim = maxAmpl < 1.2 ? INT(5 * maxAmpl) - 2 : 3

*   gtrim = ampSect > 1 ? ampSect : ampSect == 1 ? 0 : 1

*   rtrim = freqKhz > 30000 ? 0 :
*           freqMHz > 24000 ? 1 :
*           freqMHz > 17000 ? 2 : 3
*
*   ftrim = rtrim
*
*
Function Usage
/* Scenario: ECO needs to be configured. The ECO pins are configured using
* the gpio driver. The ECO crystal has the following characteristics:
* Frequency: 4.0000 MHz
* Parallel load capacitance: 20 pF
* Effective series resistance: 150 Ohms
* Drive level: 0.5 mW
*/
/* Disable the ECO before configuring */
Cy_SysClk_EcoDisable();
/* Configure the ECO with its characteristics */
if (CY_SYSCLK_SUCCESS != Cy_SysClk_EcoConfigure(4000000UL, /* 4.0000 MHz */
20UL, /* 20 pF */
150UL, /* 150 Ohms */
500UL)) /* 0.5 mW */
{
/* Insert error handling */
}
/* Enable the ECO with a timeout of 10 milliseconds */
if (CY_SYSCLK_SUCCESS != Cy_SysClk_EcoEnable(10000UL))
{
/* Insert error handling */
}
/* Check the ECO frequency, this function also
* checks if the ECO is enabled and stable
*/
uint32_t ecoFreq = Cy_SysClk_EcoGetFrequency();

◆ Cy_SysClk_EcoEnable()

cy_en_sysclk_status_t Cy_SysClk_EcoEnable ( uint32_t  timeoutUs)

Enables the external crystal oscillator (ECO).

This function should be called after Cy_SysClk_EcoConfigure.

Note
Not applicable for PSOC4 HVMS/PA.
Parameters
timeoutUsAmount of time in microseconds to wait for the ECO to stabilize. To avoid waiting for stabilization, set this parameter to 0.
Returns
Error / status code cy_en_sysclk_status_t :
CY_SYSCLK_SUCCESS - ECO is enabled
CY_SYSCLK_TIMEOUT - ECO timed out and did not stabilized
CY_SYSCLK_INVALID_STATE - ECO is not configured using Cy_SysClk_EcoConfigure.
Function Usage
/* Scenario: ECO needs to be configured. The ECO pins are configured using
* the gpio driver. The ECO crystal has the following characteristics:
* Frequency: 4.0000 MHz
* Parallel load capacitance: 20 pF
* Effective series resistance: 150 Ohms
* Drive level: 0.5 mW
*/
/* Disable the ECO before configuring */
Cy_SysClk_EcoDisable();
/* Configure the ECO with its characteristics */
if (CY_SYSCLK_SUCCESS != Cy_SysClk_EcoConfigure(4000000UL, /* 4.0000 MHz */
20UL, /* 20 pF */
150UL, /* 150 Ohms */
500UL)) /* 0.5 mW */
{
/* Insert error handling */
}
/* Enable the ECO with a timeout of 10 milliseconds */
if (CY_SYSCLK_SUCCESS != Cy_SysClk_EcoEnable(10000UL))
{
/* Insert error handling */
}
/* Check the ECO frequency, this function also
* checks if the ECO is enabled and stable
*/
uint32_t ecoFreq = Cy_SysClk_EcoGetFrequency();

◆ Cy_SysClk_EcoGetFrequency()

uint32_t Cy_SysClk_EcoGetFrequency ( void  )

Returns the frequency of the external crystal oscillator (ECO).

Note
Not applicable for PSOC4 HVMS/PA.
Returns
The frequency of the ECO.
Note
If the ECO is not enabled or stable - a zero is returned.
Function Usage
/* Scenario: ECO needs to be configured. The ECO pins are configured using
* the gpio driver. The ECO crystal has the following characteristics:
* Frequency: 4.0000 MHz
* Parallel load capacitance: 20 pF
* Effective series resistance: 150 Ohms
* Drive level: 0.5 mW
*/
/* Disable the ECO before configuring */
Cy_SysClk_EcoDisable();
/* Configure the ECO with its characteristics */
if (CY_SYSCLK_SUCCESS != Cy_SysClk_EcoConfigure(4000000UL, /* 4.0000 MHz */
20UL, /* 20 pF */
150UL, /* 150 Ohms */
500UL)) /* 0.5 mW */
{
/* Insert error handling */
}
/* Enable the ECO with a timeout of 10 milliseconds */
if (CY_SYSCLK_SUCCESS != Cy_SysClk_EcoEnable(10000UL))
{
/* Insert error handling */
}
/* Check the ECO frequency, this function also
* checks if the ECO is enabled and stable
*/
uint32_t ecoFreq = Cy_SysClk_EcoGetFrequency();

◆ Cy_SysClk_EcoIsEnabled()

__STATIC_INLINE bool Cy_SysClk_EcoIsEnabled ( void  )

Returns the ECO enable/disable state.

Note
Not applicable for PSOC4 HVMS/PA.
Returns
false = disabled
true = enabled
Function Usage
/* Scenario: If ECO is enabled and sources HFCLK then the ECO needs
* to be disabled and replaced with the IMO for HFCLK
*/
if (Cy_SysClk_EcoIsEnabled()) /* If ECO enabled */
{
/* If ECO sources HFCLK */
if ((CY_SYSCLK_CLKHF_IN_EXCO == Cy_SysClk_ClkHfGetSource()) &&
((CY_SYSCLK_PLL_BYP_ECO == Cy_SysClk_PllGetBypassState(0UL)) ||
(CY_SYSCLK_PLL_SRC_ECO == Cy_SysClk_PllGetSource(0UL))))
{
/* First update the HFCLK clock to IMO */
if (CY_SYSCLK_SUCCESS != Cy_SysClk_ClkHfSetSource(CY_SYSCLK_CLKHF_IN_IMO))
{
/* Insert error handling */
}
}
/* Disable the ECO */
Cy_SysClk_EcoDisable();
}

◆ Cy_SysClk_EcoDisable()

__STATIC_INLINE void Cy_SysClk_EcoDisable ( void  )

Disables the external crystal oscillator (ECO).

This function should not be called if the ECO is sourcing other resources.

Note
Not applicable for PSOC4 HVMS/PA.
Function Usage
/* Scenario: If ECO is enabled and sources HFCLK then the ECO needs
* to be disabled and replaced with the IMO for HFCLK
*/
if (Cy_SysClk_EcoIsEnabled()) /* If ECO enabled */
{
/* If ECO sources HFCLK */
if ((CY_SYSCLK_CLKHF_IN_EXCO == Cy_SysClk_ClkHfGetSource()) &&
((CY_SYSCLK_PLL_BYP_ECO == Cy_SysClk_PllGetBypassState(0UL)) ||
(CY_SYSCLK_PLL_SRC_ECO == Cy_SysClk_PllGetSource(0UL))))
{
/* First update the HFCLK clock to IMO */
if (CY_SYSCLK_SUCCESS != Cy_SysClk_ClkHfSetSource(CY_SYSCLK_CLKHF_IN_IMO))
{
/* Insert error handling */
}
}
/* Disable the ECO */
Cy_SysClk_EcoDisable();
}

◆ Cy_SysClk_EcoGetStatus()

__STATIC_INLINE cy_en_sysclk_eco_stat_t Cy_SysClk_EcoGetStatus ( void  )

Reports the current status of the external crystal oscillator (ECO).

Note
Not applicable for PSOC4 HVMS/PA.
This function returns just a register value, for example, CY_SYSCLK_ECO_STABLE can be returned even when ECO is not enabled. To get a precise ECO status use also Cy_SysClk_EcoIsEnabled.
Returns
cy_en_sysclk_eco_stat_t :
CY_SYSCLK_ECO_STABLE - ECO is stable.
CY_SYSCLK_ECO_WATCHDOG_ERROR - ECO oscillator is stuck.
Function Usage
/* Scenario: HFCLK needs to be switched to the ECO (if ECO is enabled, of course) */
if (Cy_SysClk_EcoIsEnabled() && (CY_SYSCLK_ECO_STABLE == Cy_SysClk_EcoGetStatus())) /* If ECO enabled and stabilized */
{
if (CY_SYSCLK_PLL_BYP_ECO != Cy_SysClk_PllGetBypassState(0U))
{
Cy_SysClk_PllBypass(0U, CY_SYSCLK_PLL_BYP_ECO); /* First make multiplexing inside the EXCO block */
}
sysclkStatus = Cy_SysClk_ClkHfSetSource(CY_SYSCLK_CLKHF_IN_EXCO);
if (CY_SYSCLK_SUCCESS != sysclkStatus)
{
/* Insert error handling */
}
}