PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

Functions
Functions
PDL API Reference » SysClk (System Clock) » External Crystal Oscillator (ECO)

## 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_EcoManualConfigure (const cy_stc_clk_eco_config_t *ecoConfig)
| 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

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

## ◆ Cy_SysClk_EcoManualConfigure()

cy_en_sysclk_status_t Cy_SysClk_EcoManualConfigure | ( | const cy_stc_clk_eco_config_t * | ecoConfig | ) |

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

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

Parameters

  ecoConfig | cy_stc_clk_eco_config_t

Note
  This API expects the trims to be calculated outside this API scope, so refer and use the ECO calculators excel sheet for the platform to obtain the trims.
  This API is not Secure Aware. It uses the PPC regions SRSS_SECURE and SRSS_MAIN. The SRSS_SECURE region is always secured. Thus, this API is only safe to call if SRSS_MAIN is also configured as secure.

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

  timeoutus | Amount 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

Note
  Call SystemCoreClockUpdate after this function calling if it affects the CLK_HF0 frequency.
  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 */
  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. */
  Cy_SysClk_EcoGetFrequency
  uint32_t Cy_SysClk_EcoGetFrequency(void)
  Returns the frequency of the external crystal oscillator (ECO).
  Definition: cy_sysclk_v2.c:4264
  Cy_SysClk_EcoEnable
  cy_en_sysclk_status_t Cy_SysClk_EcoEnable(uint32_t timeoutus)
  Enables the external crystal oscillator (ECO).
  Definition: cy_sysclk_v2.c:4226
  CY_SYSCLK_SUCCESS
  @ CY_SYSCLK_SUCCESS
  Command completed with no errors.
  Definition: cy_sysclk.h:501

## ◆ 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 */
  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. */

## ◆ 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 */
  (void)Cy_SysClk_ClkPathSetSource(2UL, CY_SYSCLK_CLKPATH_IN_IMO);
  /* Disable the ECO */
  Cy_SysClk_EcoDisable();
  Cy_SysClk_EcoDisable
  void Cy_SysClk_EcoDisable(void)
  Disables the external crystal oscillator (ECO).
  Definition: cy_sysclk_v2.c:4208
  CY_SYSCLK_CLKPATH_IN_IMO
  @ CY_SYSCLK_CLKPATH_IN_IMO
  Select the IMO as the output of the path mux.
  Definition: cy_sysclk.h:832
  Cy_SysClk_ClkPathSetSource
  cy_en_sysclk_status_t Cy_SysClk_ClkPathSetSource(uint32_t clkPath, cy_en_clkpath_in_sources_t source)
  Configures the source for the specified clock path.
  Definition: cy_sysclk_v2.c:4693

## ◆ Cy_SysClk_EcoGetStatus()

uint32_t Cy_SysClk_EcoGetStatus | ( | void |  | ) |

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

Returns
  CY_SYSCLK_ECOSTAT_UNUSABLE = ECO does not have sufficient amplitude
  CY_SYSCLK_ECOSTAT_OK = ECO has sufficient amplitude but may not be meeting accuracy and duty cycle specifications
  CY_SYSCLK_ECOSTAT_READY = ECO has sufficient time to stabilize it's power
  CY_SYSCLK_ECOSTAT_OK_AND_READY = 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_UNUSABLE:
  /* Amplitude is not sufficient. Try waiting longer before
  attempting to reconfigure the ECO */
  break;
  case CY_SYSCLK_ECOSTAT_OK:
  /* Amplitude is correct but the ECO is not yet stable. Try
  waiting longer before attempting to reconfigure the ECO */
  break;
  case CY_SYSCLK_ECOSTAT_READY:
  /* Power is correct and stable */
  break;
  case CY_SYSCLK_ECOSTAT_OK_AND_READY:
  /* ECO is stable and ready for use */
  break;
  default:
  /* Invalid state. Perform error handling. */
  break;
  }
  Cy_SysClk_EcoGetStatus
  uint32_t Cy_SysClk_EcoGetStatus(void)
  Reports the current status of the external crystal oscillator (ECO).
  Definition: cy_sysclk_v2.c:4216
  CY_SYSCLK_ECOSTAT_UNUSABLE
  #define CY_SYSCLK_ECOSTAT_UNUSABLE
  ECO does not have sufficient amplitude and not stable power.
  Definition: cy_sysclk.h:565
  CY_SYSCLK_ECOSTAT_OK
  #define CY_SYSCLK_ECOSTAT_OK
  ECO has sufficient amplitude but may not be meeting accuracy and duty cycle specifications.
  Definition: cy_sysclk.h:566
  CY_SYSCLK_ECOSTAT_READY
  #define CY_SYSCLK_ECOSTAT_READY
  ECO has sufficient time to stabilize it's power.
  Definition: cy_sysclk.h:567
  CY_SYSCLK_ECOSTAT_OK_AND_READY
  #define CY_SYSCLK_ECOSTAT_OK_AND_READY
  ECO has fully stabilized.
  Definition: cy_sysclk.h:568

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

  enable | ECO Prescaler enable/disable.
  int_div | 10-bit integer value.
  frac_div | 8-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

## ◆ Cy_SysClk_EcoPrescaleIsEnabled()

bool Cy_SysClk_EcoPrescaleIsEnabled | ( | void |  | ) |

Reports whether or not ECO Prescale is enabled.

Returns
  false = disabled
  true = enabled

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