Functions

group group_sysclk_eco_funcs

Functions

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.

note

For CAT1B Devices: cSum stands for crystal load capacitance in pF.

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
*
Return

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

Parameters
  • freq: Operating frequency of the crystal in Hz. Valid range: 16000000…35000000 (16..35 MHz).

  • cSum: The 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.

Parameters
  • esr: Effective series resistance of the crystal in Ohms. Valid range: 1…1000.

  • driveLevel: Crystal drive level in uW. Valid range: 1…2000.

note

On CAT1B 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)*

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 */
    Cy_SysClk_EcoDisable();

    /* 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 */
    if(CY_SYSCLK_SUCCESS != Cy_SysClk_EcoEnable(3000UL))
    {
        /* Insert error handling */
    }

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

Call SystemCoreClockUpdate after this function calling if it affects the CLK_HF0 frequency.

Return

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

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 */
    if(CY_SYSCLK_SUCCESS == Cy_SysClk_EcoEnable(1000UL))
    {
        ecofreq = Cy_SysClk_EcoGetFrequency();
        /* 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. */

Parameters
  • timeoutus: Amount of time in microseconds to wait for the ECO to stabilize. To avoid waiting for stabilization, set this parameter to 0.

uint32_t Cy_SysClk_EcoGetFrequency(void)

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

note

If the ECO is not enabled or stable - a zero is returned.

note

This API is available for CAT1A devices.

Return

The frequency of the ECO.

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 */
    if(CY_SYSCLK_SUCCESS == Cy_SysClk_EcoEnable(1000UL))
    {
        ecofreq = Cy_SysClk_EcoGetFrequency();
        /* 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. */

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 */
    (void)Cy_SysClk_ClkPathSetSource(2UL, CY_SYSCLK_CLKPATH_IN_IMO);

    /* Disable the ECO */
    Cy_SysClk_EcoDisable();

uint32_t Cy_SysClk_EcoGetStatus(void)

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

Return

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

Function Usage

    /* Scenario: Query the status of the ECO */

    uint32_t ecoStatus = Cy_SysClk_EcoGetStatus();

    /* Perform action based on the ECO status */
    switch(ecoStatus)
    {
        case CY_SYSCLK_ECOSTAT_AMPLITUDE:
            /* Amplitude is not sufficient. Try waiting longer before
               attempting to reconfigure the ECO */
        break;
        case CY_SYSCLK_ECOSTAT_INACCURATE:
            /* Amplitude is correct but the ECO is not yet stable. Try
               waiting longer before attempting to reconfigure the ECO */
        break;
        case CY_SYSCLK_ECOSTAT_STABLE:
            /* ECO is stable and ready for use */
        break;
        default:
            /* Invalid state. Perform error handling. */
        break;
    }