RTEMS  5.1
Data Structures | Typedefs | Functions

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

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
clkThe clock divider to get the value from.
div[out] Pointer to an output variable for the returned clock divider value.
Return values
ALT_E_SUCCESSThe operation was succesful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGAn 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
clkThe clock divider to set the value for.
divThe 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_SUCCESSThe operation was succesful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGAn invalid clock argument was specified or a clock that does not have a divider.
ALT_E_ARG_RANGEThe 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
clkThe 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
freqThe 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
clkThe external clock source. Valid external clocks are
  • ALT_CLK_OSC1
  • ALT_CLK_OSC2
  • ALT_CLK_F2H_PERIPH_REF
  • ALT_CLK_F2H_SDRAM_REF
freqThe frequency of the external clock in Hz.
Return values
ALT_E_SUCCESSThe operation was succesful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGA bad argument value was passed. Either the clk argument is bad or not a valid external clock source
ALT_E_ARG_RANGEThe 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
clkThe 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_SUCCESSThe operation was succesful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGA 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
pllThe PLL to get the configuration from.
pll_cfg[out] Pointer to an output parameter variable for the returned PLL configuration.
Return values
ALT_E_SUCCESSThe operation was succesful.
ALT_E_ERRORThe 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
pllThe PLL to set the configuration for.
pll_cfgPointer to a ALT_CLK_PLL_CFG_t structure specifying the desired PLL configuration.
Return values
ALT_E_SUCCESSThe operation was succesful.
ALT_E_ERRORThe 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
pllThe 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
pllThe PLL to set the guard band value for.
guard_bandThe guard band value. Value should be 0 <= guard_band <= 100.
Return values
ALT_E_SUCCESSThe operation was succesful.
ALT_E_ERRORThe operation failed.
ALT_E_ARG_RANGEThe 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
pllThe 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_SUCCESSThe operation was succesful.
ALT_E_ERRORThe 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
pllThe PLL to set the VCO frequency configuration for.
multThe PLL VCO multiplier (M). Expected argument range 1 to 4096.
divThe PLL VCO divider (N). Expected argument range 1 to 64.
Return values
ALT_E_SUCCESSThe operation was succesful.
ALT_E_ERRORThe 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
pllThe 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_SUCCESSThe operation was succesful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGA bad argument value was passed. Either the pll argument is invalid or a bad freq pointer value was passed.