MTB CAT1 Peripheral driver library

General Description

Functions

void Cy_SysClk_EcoSetFrequency (uint32_t freq)
 Stores the external crystal oscillator (ECO) frequency in a global variable within Sysclk driver. More...
 
cy_en_sysclk_status_t Cy_SysClk_EcoConfigure (uint32_t freq, uint32_t cSum, 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...
 
void Cy_SysClk_EcoDisable (void)
 Disables the external crystal oscillator (ECO). More...
 
uint32_t Cy_SysClk_EcoGetStatus (void)
 Reports the current status of the external crystal oscillator (ECO). More...
 
cy_en_sysclk_status_t Cy_SysClk_EcoPrescaleConfigure (uint32_t enable, uint32_t int_div, uint32_t frac_div)
 Configures the external crystal oscillator (ECO) using ECO Prescaler Configuration Register and derives clk_eco_prescaler. More...
 
bool Cy_SysClk_EcoPrescaleIsEnabled (void)
 Reports whether or not ECO Prescale is enabled. More...
 
uint32_t Cy_SysClk_EcoPrescaleGetFrequency (void)
 Returns the frequency of the external crystal oscillator (ECO) prescaler. More...
 

Function Documentation

◆ Cy_SysClk_EcoSetFrequency()

void Cy_SysClk_EcoSetFrequency ( uint32_t  freq)

Stores the external crystal oscillator (ECO) frequency in a global variable within Sysclk driver.

Parameters
freqOperating frequency of the crystal in Hz. Valid range: 16000000...35000000 (16..35 MHz).
Note
This API is available for CAT1A (excluding TVIIBE), CAT1B, CAT1C and CAT1D devices.

◆ Cy_SysClk_EcoConfigure()

cy_en_sysclk_status_t Cy_SysClk_EcoConfigure ( uint32_t  freq,
uint32_t  cSum,
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.

Parameters
freqOperating frequency of the crystal in Hz. Valid range: 16000000...35000000 (16..35 MHz).
cSumThe summary capacitance of C0 (the crystal itself shunt capacitance) and Cload (the parallel load capacitance), in pF. So cSum = C0 + Cload. Valid range: 1...100.
Note
For CAT1B Devices: cSum stands for crystal load capacitance in pF.
Parameters
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_SYSCLK_SUCCESS - ECO configuration completed successfully
CY_SYSCLK_BAD_PARAM - One or more invalid parameters
CY_SYSCLK_INVALID_STATE - ECO already enabled
Note
Behavior of this API is IP dependent.
On CAT1A device:
For the PSoC 64 devices there are possible situations when function returns the PRA error status code. This is because for PSoC 64 devices the function uses the PRA driver to change the protected registers. Refer to cy_en_pra_status_t for more details. The following calculations are implemented in the 32-bit integer math: On PSoC 64 devices the configuration on the PRA driver will be reflected after Cy_SysClk_EcoEnable call.
*   freqKhz = freq / 1000
*   maxAmpl = sqrt(drivelevel / 2 / esr) / 3.14 / freqKhz / cSum
*   ampSect = INT(5 * 4 * 3.14^2 * freqKhz^2 * cSum^2 * 4 * esr / 1000000000 / 1000000 / 9)
*   As a result of the above calculations, max amplitude must be >= 0.65V, and the
*   number of amplifier sections must be <= 3, otherwise this function returns with
*   a parameter error.
*
*   atrim = 15
*   agc_en = 1
*   wdtrim = 7
*   gtrim = ampSect > 1 ? ampSect : ampSect == 1 ? 0 : 1
*   rtrim = 0
*   ftrim = 3
* 
Note
On CAT1C Device:
*   No TRIM registers configuration required for CAT1B devices, For legacy API is emptied
*   The following calculations are implemented, generally in floating point:
*   freqMHz = freq / 1000000
*   max amplitude Vpp = 1000 * sqrt(drivelevel / 2 / esr) / 3.14 / freqMHz / cLoad
*   gm_min mA/V = 5 * 4 * 3.14 * 3.14 * freqMhz^2 * cLoad^2 * 4 * esr / 1000000000
*   Number of amplifier sections = INT(gm_min / 4.5)
*
*   As a result of the above calculations, max amplitude must be >= 0.5, and the
*   number of amplifier sections must be <= 3, otherwise this function returns with
*   a parameter error.
*
*   atrim = if (max amplitude < 0.5) then error
*           else 2 * the following:
*                    max amplitude < 0.6: 0
*                    max amplitude < 0.7: 1
*                    max amplitude < 0.8: 2
*                    max amplitude < 0.9: 3
*                    max amplitude < 1.15: 5
*                    max amplitude < 1.275: 6
*                    max amplitude >= 1.275: 7
*   wdtrim = if (max amplitude < 0.5) then error
*            else 2 * the following:
*                     max amplitude < 1.2: INT(5 * max amplitude) - 2
*                     max amplitude >= 1.2: 3
*   gtrim = if (number of amplifier sections > 3) then error
*           else the following:
*                number of amplifier sections > 1: number of amplifier sections
*                number of amplifier sections = 1: 0
*                number of amplifier sections < 1: 1
*   rtrim = if (gtrim = error) then error
*           else the following:
*                freqMHz > 26.8: 0
*                freqMHz > 23.33: 1
*                freqMHz > 16.5: 2
*                freqMHz <= 16.5: 3
*   ftrim = if (atrim = error) then error
*           else INT(atrim / 2)
* 
This API is available for CAT1A, CAT1C and CAT1D devices.
Function Usage
/* Scenario: ECO needs to be configured. The ECO pins are configured using
the gpio driver (SRSS_ECO_IN_PIN, SRSS_ECO_OUT_PIN). The ECO
crystal has the following characteristics:
Frequency: 17.2032 MHz
Parallel load crystal capacitance: 22 pF
Crystal shunt capacitance: 7 pF
Effective series resistance: 40 Ohm
Drive level: 500 uW */
/* Disable the ECO before configuring */
/* Configure the ECO with its characteristics */
if(CY_SYSCLK_SUCCESS != Cy_SysClk_EcoConfigure(17203200UL, /* 17.2032 MHz */
29UL, /* 7 pF C0 + 22 pF Cload */
40UL, /* 40 Ohms */
500UL)) /* 500 uW */
{
/* Insert error handling */
}
/* Enable the ECO with a timeout of 3000 microseconds */
{
/* Insert error handling */
}

◆ 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.

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_SYSCLK_SUCCESS - ECO locked
CY_SYSCLK_TIMEOUT - ECO timed out and did not lock
CY_SYSCLK_INVALID_STATE - ECO already enabled
CY_SYSCLK_UNSUPPORTED_STATE - ECO is not present For the PSoC 64 devices there are possible situations when function returns the PRA error status code. This is because for PSoC 64 devices the function uses the PRA driver to change the protected registers. Refer to cy_en_pra_status_t for more details.
Note
Call SystemCoreClockUpdate after this function calling if it affects the CLK_HF0 frequency.
This API is available for CAT1A & CAT1C devices.
Take into account the possible platform specific clkHf (and further clocking chain links) frequency limitations while using this API.
Function Usage
/* Scenario: ECO is successfully configured and needs to be enabled. The
ECO pins are configured using the gpio driver
(SRSS_ECO_IN_PIN, SRSS_ECO_OUT_PIN). */
uint32_t ecofreq = 0UL; /* Variable to store the ECO frequency */
/* Enable the ECO with a timeout of 1000 microseconds */
{
/* Now ecofreq contains an actual ECO frequency */
}
else
{
/* Insert error handling */
}
/* Set the path muxes and configure the downstream clocks. For example,
the ECO can source the FLL through path 0 clock or it can source the PLL
through path 1 clock. */

◆ Cy_SysClk_EcoGetFrequency()

uint32_t Cy_SysClk_EcoGetFrequency ( void  )

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

Returns
The frequency of the ECO.
Note
If the ECO is not enabled or stable - a zero is returned.
Function Usage
/* Scenario: ECO is successfully configured and needs to be enabled. The
ECO pins are configured using the gpio driver
(SRSS_ECO_IN_PIN, SRSS_ECO_OUT_PIN). */
uint32_t ecofreq = 0UL; /* Variable to store the ECO frequency */
/* Enable the ECO with a timeout of 1000 microseconds */
{
/* Now ecofreq contains an actual ECO frequency */
}
else
{
/* Insert error handling */
}
/* Set the path muxes and configure the downstream clocks. For example,
the ECO can source the FLL through path 0 clock or it can source the PLL
through path 1 clock. */
Note
This API is available for CAT1A, CAT1B(PSoC C3), CAT1C & CAT1D devices.

◆ Cy_SysClk_EcoDisable()

void Cy_SysClk_EcoDisable ( void  )

Disables the external crystal oscillator (ECO).

This function should not be called if the ECO is sourcing clkHf[0].

Function Usage
/* Scenario: ECO sources path 2 clock, which sources HFCLK2. The ECO needs
to be disabled and replaced with the IMO for HFCLK2 */
/* Update the path 2 clock to IMO */
/* Disable the ECO */
Note
This API is available for CAT1A, CAT1C devices.

◆ Cy_SysClk_EcoGetStatus()

uint32_t Cy_SysClk_EcoGetStatus ( void  )

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

Returns
CY_SYSCLK_ECOSTAT_AMPLITUDE = ECO does not have sufficient amplitude
CY_SYSCLK_ECOSTAT_INACCURATE = ECO has sufficient amplitude but may not be meeting accuracy and duty cycle specifications
CY_SYSCLK_ECOSTAT_STABLE = ECO has fully stabilized
Note
This API is available for CAT1A, CAT1C devices.
Function Usage
/* Scenario: Query the status of the ECO */
uint32_t ecoStatus = Cy_SysClk_EcoGetStatus();
/* Perform action based on the ECO status */
switch(ecoStatus)
{
/* Amplitude is not sufficient. Try waiting longer before
attempting to reconfigure the ECO */
break;
/* Amplitude is correct but the ECO is not yet stable. Try
waiting longer before attempting to reconfigure the ECO */
break;
/* ECO is stable and ready for use */
break;
default:
/* Invalid state. Perform error handling. */
break;
}

◆ Cy_SysClk_EcoPrescaleConfigure()

cy_en_sysclk_status_t Cy_SysClk_EcoPrescaleConfigure ( uint32_t  enable,
uint32_t  int_div,
uint32_t  frac_div 
)

Configures the external crystal oscillator (ECO) using ECO Prescaler Configuration Register and derives clk_eco_prescaler.

Parameters
enableECO Prescaler enable/disable.
int_div10-bit integer value.
frac_div8-bit fraction value.
Returns
Error / status code:
CY_SYSCLK_SUCCESS - ECO configuration completed successfully
CY_SYSCLK_BAD_PARAM - One or more invalid parameters
CY_SYSCLK_INVALID_STATE - ECO already enabled
CY_SYSCLK_UNSUPPORTED_STATE - ECO is not present
Note
This API is available for CAT1A (TVIIBE only) and CAT1C devices.

◆ Cy_SysClk_EcoPrescaleIsEnabled()

bool Cy_SysClk_EcoPrescaleIsEnabled ( void  )

Reports whether or not ECO Prescale is enabled.

Returns
false = disabled
true = enabled
Note
This API is available for CAT1A (TVIIBE only) and CAT1C devices.

◆ Cy_SysClk_EcoPrescaleGetFrequency()

uint32_t Cy_SysClk_EcoPrescaleGetFrequency ( void  )

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

Returns
The frequency of the ECO Prescaler.
Note
If the ECO is not enabled or stable - a zero is returned.
This API is available for CAT1B(PSoC C3), CAT1C & CAT1D devices.