Clock Frequency Control

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.