Clock

General Description

Interface for enabling or disabling the clock and updating the clock frequency.

Features

• Enable/disable the clock
• Update the clock frequency

Code snippets

Note

Error checking is omitted for clarity

Snippet 1: Defining and using a custom clock

interface, both directly and passing to a HAL driver to manipulate.

uint32_t my_custom_get_clock_freq(const void* clk)
{
    /* Custom get_frequency function for our clock */
    CY_UNUSED_PARAMETER(clk);
    return 100000;
}
 
 
cy_rslt_t my_custom_set_clock_freq(const void* clk, uint32_t frequency, uint32_t tolerance_ppm)
{
    /* Custom set_frequency function for our clock */
    CY_UNUSED_PARAMETER(clk);
    CY_UNUSED_PARAMETER(frequency);
    CY_UNUSED_PARAMETER(tolerance_ppm);
    return CY_RSLT_SUCCESS;
}
 
 
cy_rslt_t my_custom_set_clock_enabled(const void* clk, bool enable)
{
    /* Custom set_enable function for our clock */
    CY_UNUSED_PARAMETER(clk);
    CY_UNUSED_PARAMETER(enable);
    return CY_RSLT_SUCCESS;
}
 
 
/* These are generated by the device configurator */
#define my_clk_GRP_NUM  (0)
#define my_clk_HW       (0)
#define my_clk_NUM      (0)
 
void snippet_mtb_hal_clock_custom_interface(void)
{
    uint32_t current_freq_hz = 0;
    uint32_t target_freq_hz  = 100000;
    uint32_t tolerance_ppm   = 20000;
    cy_rslt_t result;
    mtb_hal_uart_t uart_obj;
    cy_stc_scb_uart_context_t uart_context;
    // UART_hal_config is generated and populated by device configurator
    const mtb_hal_uart_configurator_t UART_hal_config = { 0 };
 
    mtb_hal_peri_div_t peri_div =
    {
        .clk_dst  = (en_clk_dst_t)my_clk_GRP_NUM,
        .div_type = (cy_en_divider_types_t)my_clk_HW,
        .div_num  = my_clk_NUM
    };
 
    /* Bundle custom clock APIs in an interface structure */
    mtb_hal_clock_interface_t interface =
    {
        .get_frequency_hz = my_custom_get_clock_freq,
        .set_frequency_hz = my_custom_set_clock_freq,
        .set_enabled      = my_custom_set_clock_enabled
    };
 
    mtb_hal_clock_t clock_obj =
    {
        .clock_ref = &peri_div,
        .interface = &interface
    };
 
    /* Clock interface APIs may be called directly:
     * For example - check if our clock is operating at the right frequency, and if not update it */
    clock_obj.interface->set_enabled(clock_obj.clock_ref, true);
    current_freq_hz = clock_obj.interface->get_frequency_hz(clock_obj.clock_ref);
    if (current_freq_hz != target_freq_hz)
    {
        result = clock_obj.interface->set_frequency_hz(clock_obj.clock_ref, target_freq_hz,
                                                       tolerance_ppm);
        if (result != CY_RSLT_SUCCESS)
        {
            /* Handle error */
        }
    }
 
    /* Some HALs use and manipulate clocks.  Providing a custom clock object will result in the HAL
       using that
     * clock instead of one set up via the device configurator */
    result = mtb_hal_uart_setup(&uart_obj, &UART_hal_config, &uart_context, &clock_obj);
    /* Perform additional IP-specific PDL setup to initialize peripheral */
 
    /* This HAL API will use the custom interface APIs */
    result = mtb_hal_uart_set_baud(&uart_obj, BAUD_RATE, NULL);
}
 
 

• Interface for getting and changing clock configuration

The clock driver is a single interface designed to allow reading and configuring any clock in the system.

API Reference
	Clock HAL Results
	Clock specific return codes.

Data Structures
struct	mtb_hal_clock_tolerance_t
	Structure defining a clock tolerance. More...

Macros
#define	mtb_hal_clock_interface   mtb_hal_clock_peri_interface
	TODO: Temporarily preserved for backwards compatibility.

Enumerations
enum	mtb_hal_clock_tolerance_unit_t {   MTB_HAL_TOLERANCE_HZ ,   MTB_HAL_TOLERANCE_PPM ,   MTB_HAL_TOLERANCE_PERCENT }
	Enum defining the different ways of specifying the acceptable clock tolerance. More...

Functions
cy_rslt_t	mtb_hal_clock_set_enabled (mtb_hal_clock_t *clock, bool enabled, bool wait_for_lock)
	Attempts to update the enablement of the specified clock. More...
cy_rslt_t	mtb_hal_clock_set_frequency (mtb_hal_clock_t *clock, uint32_t hz, const mtb_hal_clock_tolerance_t *tolerance)
	Attempts to update the operating frequency of the clock. More...
uint32_t	mtb_hal_clock_get_peri_clock_freq (const void *clk)
	Gets the frequency in hertz the peripheral clock is currently operating at. More...
cy_rslt_t	mtb_hal_clock_set_peri_clock_freq (const void *clk, uint32_t frequency, uint32_t tolerance_ppm)
	Update the operating frequency of the peripheral clock. More...
cy_rslt_t	mtb_hal_clock_set_peri_clock_enabled (const void *clk, bool enable)
	Enable/Disable the peripheral clock. More...
uint32_t	mtb_hal_clock_get_peri_src_clock_freq (const void *clk)
	Gets the peripheral source clock frequency that is feeding the clock tree for the specified resource. More...
uint32_t	mtb_hal_clock_get_hf_clock_freq (const void *clk)
	Gets the frequency in hertz the high frequency clock is currently operating at. More...
cy_rslt_t	mtb_hal_clock_set_hf_clock_freq (const void *clk, uint32_t frequency, uint32_t tolerance_ppm)
	Update the operating frequency of the high frequency clock. More...
cy_rslt_t	mtb_hal_clock_set_hf_clock_enabled (const void *clk, bool enable)
	Enable/Disable the high frequency clock. More...

Variables
const mtb_hal_clock_interface_t	mtb_hal_clock_peri_interface
	Default global interface for peripheral clocks.
const mtb_hal_clock_interface_t	mtb_hal_clock_hf_interface
	Default global interface for high freqeuncy clocks.

---

Data Structure Documentation

mtb_hal_clock_tolerance_t

struct mtb_hal_clock_tolerance_t

Data Fields
mtb_hal_clock_tolerance_unit_t	type	The type of the clock tolerance value.
uint32_t	value	The tolerance value to use.

Enumeration Type Documentation

mtb_hal_clock_tolerance_unit_t

enum mtb_hal_clock_tolerance_unit_t

Enum defining the different ways of specifying the acceptable clock tolerance.

Enumerator
MTB_HAL_TOLERANCE_HZ	Clock tolerance specified directly in Hertz.
MTB_HAL_TOLERANCE_PPM	Clock tolerance specified in parts-per-million.
MTB_HAL_TOLERANCE_PERCENT	Clock tolerance specified in a percent.

Function Documentation

mtb_hal_clock_set_enabled()

cy_rslt_t mtb_hal_clock_set_enabled	(	mtb_hal_clock_t *	clock,
		bool	enabled,
		bool	wait_for_lock
	)

Attempts to update the enablement of the specified clock.

Note

If disabled, any clocks or peripherals that are using this will stop working. Make sure to switch the clock source of any downstream clocks if necessary to keep them running prior to disabling their source.

Parameters

[in]	clock	The clock object to update the enablement of.
[in]	enabled	Whether the clock should be enabled (true) or disabled (false).
[in]	wait_for_lock	Whether to wait for the clock to enable & lock (true), or just send the request and return (false). Most clocks behave the same either way, however Crystals, PLLs, and similar require time to lock. If false, the clocks enabled state needs be checked before using the clock.

Returns

The status of the requested to change the clocks enablement.

mtb_hal_clock_set_frequency()

cy_rslt_t mtb_hal_clock_set_frequency	(	mtb_hal_clock_t *	clock,
		uint32_t	hz,
		const mtb_hal_clock_tolerance_t *	tolerance
	)

Attempts to update the operating frequency of the clock.

Note

Some clocks (eg: FLLs & PLLs) may need to be stopped before their frequency can be changed. This function will take care of disabling & re-enabling as necessary, however, this can cause a temporary glitch on anything that is running off of the clock at the time. If glitch free operation is required, change the source of any downstream clocks the application before changing the clock frequency.

Parameters

[in]	clock	The clock object to set the frequency for.
[in]	hz	The frequency, in hertz, to set the clock to.
[in]	tolerance	The allowed tolerance from the desired hz that is acceptable, use NULL if no tolerance check is required.

Returns

The status of the request to set the clock frequency.

mtb_hal_clock_get_peri_clock_freq()

uint32_t mtb_hal_clock_get_peri_clock_freq

(

const void *

clk

)

Gets the frequency in hertz the peripheral clock is currently operating at.

Parameters

[in]

clk

Clock reference. For peri clock, expected clock object is of type mtb_hal_peri_div_t*

Returns

The frequency the clock is currently running at

mtb_hal_clock_set_peri_clock_freq()

cy_rslt_t mtb_hal_clock_set_peri_clock_freq	(	const void *	clk,
		uint32_t	frequency,
		uint32_t	tolerance_ppm
	)

Update the operating frequency of the peripheral clock.

Parameters

[in]	clk	Clock reference. For peri clock, expected clock object is of type mtb_hal_peri_div_t*
[in]	frequency	Desired clock frequency
[in]	tolerance_ppm	The allowed tolerance in the units of PPM from the desired frequency that is acceptable ,

Returns

The result of the request to set the clock frequency.

mtb_hal_clock_set_peri_clock_enabled()

cy_rslt_t mtb_hal_clock_set_peri_clock_enabled	(	const void *	clk,
		bool	enable
	)

Enable/Disable the peripheral clock.

Parameters

[in]	clk	Clock reference. For peri clock, expected clock object is of type mtb_hal_peri_div_t*
[in]	enable	true to enable. false to diable

Returns

The result of the enable/disable request

mtb_hal_clock_get_peri_src_clock_freq()

uint32_t mtb_hal_clock_get_peri_src_clock_freq

(

const void *

clk

)

Gets the peripheral source clock frequency that is feeding the clock tree for the specified resource.

Parameters

[in]

clk

Clock reference. For peri clock, expected clock object is of type mtb_hal_peri_div_t*

Returns

The peripheral clock frequency for the provided resource type

mtb_hal_clock_get_hf_clock_freq()

uint32_t mtb_hal_clock_get_hf_clock_freq

(

const void *

clk

)

Gets the frequency in hertz the high frequency clock is currently operating at.

Parameters

[in]

clk

Clock reference. For HF clock, expected clock object is of type mtb_hal_hf_clock_t*

Returns

The frequency the clock is currently running at

mtb_hal_clock_set_hf_clock_freq()

cy_rslt_t mtb_hal_clock_set_hf_clock_freq	(	const void *	clk,
		uint32_t	frequency,
		uint32_t	tolerance_ppm
	)

Update the operating frequency of the high frequency clock.

Note

currently this operation is not supported and will always return an error

Parameters

[in]	clk	Clock reference. For HF clock, expected clock object is of type mtb_hal_hf_clock_t*
[in]	frequency	Desired clock frequency
[in]	tolerance_ppm	The allowed tolerance in the units of PPM from the desired frequency that is acceptable ,

Returns

The result of the request to set the clock frequency.

mtb_hal_clock_set_hf_clock_enabled()

cy_rslt_t mtb_hal_clock_set_hf_clock_enabled	(	const void *	clk,
		bool	enable
	)

Enable/Disable the high frequency clock.

Parameters

[in]	clk	Clock reference. For HF clock, expected clock object is of type mtb_hal_hf_clock_t*
[in]	enable	true to enable. false to diable

Returns

The result of the enable/disable request