RTEMS: Clock Frequency Control

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Data Structures | Typedefs | Functions
Clock Frequency Control
Board Support Packages » ARM » Intel Cyclone V » Contributed Code » The Clock Manager API

## Data Structures
struct | ALT_CLK_PLL_CFG_s

## Typedefs
typedef struct ALT_CLK_PLL_CFG_s | ALT_CLK_PLL_CFG_t

## Functions
ALT_STATUS_CODE | alt_clk_ext_clk_freq_set (ALT_CLK_t clk, alt_freq_t freq)
alt_freq_t | alt_clk_ext_clk_freq_get (ALT_CLK_t clk)
ALT_STATUS_CODE | alt_clk_pll_cfg_get (ALT_CLK_t pll, ALT_CLK_PLL_CFG_t *pll_cfg)
ALT_STATUS_CODE | alt_clk_pll_cfg_set (ALT_CLK_t pll, const ALT_CLK_PLL_CFG_t *pll_cfg)
ALT_STATUS_CODE | alt_clk_pll_vco_cfg_get (ALT_CLK_t pll, uint32_t *mult, uint32_t *div)
ALT_STATUS_CODE | alt_clk_pll_vco_cfg_set (ALT_CLK_t pll, uint32_t mult, uint32_t div)
ALT_STATUS_CODE | alt_clk_pll_vco_freq_get (ALT_CLK_t pll, alt_freq_t *freq)
uint32_t | alt_clk_pll_guard_band_get (ALT_CLK_t pll)
ALT_STATUS_CODE | alt_clk_pll_guard_band_set (ALT_CLK_t pll, uint32_t guard_band)
ALT_STATUS_CODE | alt_clk_divider_get (ALT_CLK_t clk, uint32_t *div)
ALT_STATUS_CODE | alt_clk_divider_set (ALT_CLK_t clk, uint32_t div)
ALT_STATUS_CODE | alt_clk_freq_get (ALT_CLK_t clk, alt_freq_t *freq)

## Detailed Description

This API group provides access and control of the output frequency of a clock or PLL.

## Typedef Documentation

## ◆ ALT_CLK_PLL_CFG_t

typedef struct ALT_CLK_PLL_CFG_s ALT_CLK_PLL_CFG_t

This type definition defines a structure to contain the generalized configuration settings for a PLL.

## Function Documentation

## ◆ alt_clk_divider_get()

ALT_STATUS_CODE alt_clk_divider_get | ( | ALT_CLK_t | clk,
|  | uint32_t * | div
| ) |  |

Get the configured divider value for the specified clock.

This function is used to get the configured values of both internal and external clock dividers. The internal divider (PLL counters C0-C5) values are retrieved by specifying the clock name that is the divider output (e.g. ALT_CLK_MPU is used to get the Main PLL C0 counter value).
It returns the actual divider value, not the encoded bitfield stored in the register, due to the variety of different encodings.

Parameters

  clk | The clock divider to get the value from.
  div | [out] Pointer to an output variable for the returned clock divider value.

Return values

  ALT_E_SUCCESS | The operation was succesful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | An invalid clock argument was specified or a clock that does not have a divider.

## ◆ alt_clk_divider_set()

ALT_STATUS_CODE alt_clk_divider_set | ( | ALT_CLK_t | clk,
|  | uint32_t | div
| ) |  |

Set the divider value for the specified clock.

This function is used to set the values of both internal and external clock dividers. The internal divider (PLL counters C0-C5) values are set by specifying the clock name that is the divider output (e.g. ALT_CLK_MPU is used to set the Main PLL C0 counter value).

Parameters

  clk | The clock divider to set the value for.
  div | The clock divider value. NOTE: The valid range of clock divider values depends on the clock being configured. This is the real divisor ratio, not how the divisor is coded into the register, and is always one or greater.

Return values

  ALT_E_SUCCESS | The operation was succesful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | An invalid clock argument was specified or a clock that does not have a divider.
  ALT_E_ARG_RANGE | The divider value violates the range constraints for the clock divider.

## ◆ alt_clk_ext_clk_freq_get()

alt_freq_t alt_clk_ext_clk_freq_get | ( | ALT_CLK_t | clk | ) |

Get the external clock frequency value.

This function returns the frequency of the external clock source as a measure of Hz.

Parameters

  clk | The external clock source. Valid external clocks are ALT_CLK_OSC1 ALT_CLK_OSC2 ALT_CLK_F2H_PERIPH_REF ALT_CLK_F2H_SDRAM_REF

Return values

  freq | The frequency of the external clock in Hz.

## ◆ alt_clk_ext_clk_freq_set()

ALT_STATUS_CODE alt_clk_ext_clk_freq_set | ( | ALT_CLK_t | clk,
|  | alt_freq_t | freq
| ) |  |

Set the external clock frequency value.

The function is used to specify the frequency of the external clock source as a measure of Hz. The supplied frequency should be within the Fmin and Fmax values allowed for the external clock source.

Parameters

  clk | The external clock source. Valid external clocks are ALT_CLK_OSC1 ALT_CLK_OSC2 ALT_CLK_F2H_PERIPH_REF ALT_CLK_F2H_SDRAM_REF
  freq | The frequency of the external clock in Hz.

Return values

  ALT_E_SUCCESS | The operation was succesful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | A bad argument value was passed. Either the clk argument is bad or not a valid external clock source
  ALT_E_ARG_RANGE | The frequency value violates the range constraints for the specified clock.

## ◆ alt_clk_freq_get()

ALT_STATUS_CODE alt_clk_freq_get | ( | ALT_CLK_t | clk,
|  | alt_freq_t * | freq
| ) |  |

Get the output frequency of the specified clock.

Parameters

  clk | The clock to retrieve the output frequency from.
  freq | [out] Pointer to the an output parameter variable to return the clock output frequency value. The frequency value is returned as a measures of Hz.

Return values

  ALT_E_SUCCESS | The operation was succesful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | A bad argument value was passed. Either the clk argument is invalid or a bad freq pointer value was passed.

## ◆ alt_clk_pll_cfg_get()

ALT_STATUS_CODE alt_clk_pll_cfg_get | ( | ALT_CLK_t | pll,
|  | ALT_CLK_PLL_CFG_t * | pll_cfg
| ) |  |

Get the current PLL configuration.

Parameters

  pll | The PLL to get the configuration from.
  pll_cfg | [out] Pointer to an output parameter variable for the returned PLL configuration.

Return values

  ALT_E_SUCCESS | The operation was succesful.
  ALT_E_ERROR | The operation failed.

## ◆ alt_clk_pll_cfg_set()

ALT_STATUS_CODE alt_clk_pll_cfg_set | ( | ALT_CLK_t | pll,
|  | const ALT_CLK_PLL_CFG_t * | pll_cfg
| ) |  |

Set the PLL configuration using the configuration parameters specified in pll_cfg.

Parameters

  pll | The PLL to set the configuration for.
  pll_cfg | Pointer to a ALT_CLK_PLL_CFG_t structure specifying the desired PLL configuration.

Return values

  ALT_E_SUCCESS | The operation was succesful.
  ALT_E_ERROR | The operation failed.

## ◆ alt_clk_pll_guard_band_get()

uint32_t alt_clk_pll_guard_band_get | ( | ALT_CLK_t | pll | ) |

Get the PLL frequency guard band value.

Parameters

  pll | The PLL from which to return the current guard band value.

Returns
  The current guard band range in effect for the PLL.

## ◆ alt_clk_pll_guard_band_set()

ALT_STATUS_CODE alt_clk_pll_guard_band_set | ( | ALT_CLK_t | pll,
|  | uint32_t | guard_band
| ) |  |

Set the PLL frequency guard band value.

Once a PLL has achieved lock, any changes to the PLL VCO frequency that are within a specific guard band range (default value 20%) of the reference period should not cause the PLL to lose lock.

Programmatic changes to the PLL frequency within this guard band range are permitted to be made without the risk of breaking lock during the transition to the new frequency.

The clk_mgr_pll_guard_band_set() function changes the guard band from its current value to permit a more lenient or stringent policy to be in effect in the implementation of the functions configuring PLL VCO frequency. The rationale for changing the default guard band value might be to accommodate unexpected environmental conditions (noise, temperature, and other instability factors) that may affect the PLLs ability to maintain lock during a frequency change.

Parameters

  pll | The PLL to set the guard band value for.
  guard_band | The guard band value. Value should be 0 <= guard_band <= 100.

Return values

  ALT_E_SUCCESS | The operation was succesful.
  ALT_E_ERROR | The operation failed.
  ALT_E_ARG_RANGE | The guard band value violates its range constraint.

## ◆ alt_clk_pll_vco_cfg_get()

ALT_STATUS_CODE alt_clk_pll_vco_cfg_get | ( | ALT_CLK_t | pll,
|  | uint32_t * | mult,
|  | uint32_t * | div
| ) |  |

Get the current PLL VCO frequency configuration.

Parameters

  pll | The PLL to get the VCO frequency configuration for.
  mult | [out] Pointer to an output variable for the returned configured PLL VCO multiplier (M) value.
  div | [out] Pointer to an output variable for the returned configured PLL VCO divider (N) value.

Return values

  ALT_E_SUCCESS | The operation was succesful.
  ALT_E_ERROR | The operation failed.

## ◆ alt_clk_pll_vco_cfg_set()

ALT_STATUS_CODE alt_clk_pll_vco_cfg_set | ( | ALT_CLK_t | pll,
|  | uint32_t | mult,
|  | uint32_t | div
| ) |  |

Set the PLL VCO frequency configuration using the supplied multiplier and divider arguments.

Parameters

  pll | The PLL to set the VCO frequency configuration for.
  mult | The PLL VCO multiplier (M). Expected argument range 1 to 4096.
  div | The PLL VCO divider (N). Expected argument range 1 to 64.

Return values

  ALT_E_SUCCESS | The operation was succesful.
  ALT_E_ERROR | The operation failed.

## ◆ alt_clk_pll_vco_freq_get()

ALT_STATUS_CODE alt_clk_pll_vco_freq_get | ( | ALT_CLK_t | pll,
|  | alt_freq_t * | freq
| ) |  |

Get the VCO frequency of the specified PLL.

Parameters

  pll | The PLL to retrieve the VCO frequency from.
  freq | [out] Pointer to the an output parameter variable to return the PLL VCO frequency value. The frequency value is returned as a measures of Hz.

Return values

  ALT_E_SUCCESS | The operation was succesful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | A bad argument value was passed. Either the pll argument is invalid or a bad freq pointer value was passed.