PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference | Data Structures | Macros | Enumerations | Functions | Variables
Clock
HAL API Reference » HAL Drivers

## 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);
}
mtb_hal_uart_set_baud
cy_rslt_t mtb_hal_uart_set_baud(mtb_hal_uart_t *obj, uint32_t baudrate, uint32_t *actualbaud)
Configure the baud rate.
Definition: mtb_hal_uart.c:577
cy_rslt_t
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:459
CY_RSLT_SUCCESS
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:486
cy_stc_scb_uart_context_t
UART context structure.
Definition: cy_scb_uart.h:555
cy_en_divider_types_t
cy_en_divider_types_t
Programmable clock divider types.
Definition: cy_sysclk.h:3335
mtb_hal_clock_interface_t
Clock Interface structure for clocks.
Definition: mtb_hal_hw_types_clock_srss.h:68
mtb_hal_clock_interface_t::set_frequency_hz
mtb_hal_clock_set_frequency_hz_t set_frequency_hz
Set the clock frequency.
Definition: mtb_hal_hw_types_clock_srss.h:70
mtb_hal_clock_interface_t::set_enabled
mtb_hal_clock_set_enabled_t set_enabled
Enable or Disable the clock.
Definition: mtb_hal_hw_types_clock_srss.h:71
mtb_hal_clock_interface_t::get_frequency_hz
mtb_hal_clock_get_frequency_hz_t get_frequency_hz
Get the clock frequency.
Definition: mtb_hal_hw_types_clock_srss.h:69
mtb_hal_clock_t
Clock object Application shall provide implementations for the functions needed by the clock object.
Definition: mtb_hal_hw_types_clock_srss.h:80
mtb_hal_clock_t::interface
const mtb_hal_clock_interface_t * interface
Struct of interface functions that should be used with this clock.
Definition: mtb_hal_hw_types_clock_srss.h:85
mtb_hal_clock_t::clock_ref
const void * clock_ref
Pointer that is passed to all interface functions.
Definition: mtb_hal_hw_types_clock_srss.h:83
mtb_hal_peri_div_t
Clock Reference Structure in case of peri divider.
Definition: mtb_hal_hw_types_clock_srss.h:45
mtb_hal_peri_div_t::clk_dst
en_clk_dst_t clk_dst
PDL uses the target IP to identify the peri group.
Definition: mtb_hal_hw_types_clock_srss.h:46
mtb_hal_uart_configurator_t
UART configurator struct.
Definition: mtb_hal_hw_types_uart_scb.h:105
mtb_hal_uart_t
UART object.
Definition: mtb_hal_hw_types_uart_scb.h:77

- 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