RA Flexible Software Package Documentation  Release v4.1.0

 
CGC Interface

Detailed Description

Interface for clock generation.

Summary

The CGC interface provides the ability to configure and use all of the CGC module's capabilities. Among the capabilities is the selection of several clock sources to use as the system clock source. Additionally, the system clocks can be divided down to provide a wide range of frequencies for various system and peripheral needs.

Clock stability can be checked and clocks may also be stopped to save power when not needed. The API has a function to return the frequency of the system and system peripheral clocks at run time. There is also a feature to detect when the main oscillator has stopped, with the option of calling a user provided callback function.

The CGC interface is implemented by:

Data Structures

struct  cgc_callback_args_t
 
struct  cgc_pll_cfg_t
 
struct  cgc_divider_cfg_t
 
struct  cgc_cfg_t
 
struct  cgc_clocks_cfg_t
 
struct  cgc_api_t
 
struct  cgc_instance_t
 

Typedefs

typedef void cgc_ctrl_t
 

Enumerations

enum  cgc_event_t
 
enum  cgc_clock_t
 
enum  cgc_pll_div_t
 
enum  cgc_pll_out_div_t
 
enum  cgc_sys_clock_div_t
 
enum  cgc_usb_clock_div_t
 
enum  cgc_clock_change_t
 

Data Structure Documentation

◆ cgc_callback_args_t

struct cgc_callback_args_t

Callback function parameter data

Data Fields
cgc_event_t event The event can be used to identify what caused the callback.
void const * p_context Placeholder for user data.

◆ cgc_pll_cfg_t

struct cgc_pll_cfg_t

Clock configuration structure - Used as an input parameter to the cgc_api_t::clockStart function for the PLL clock.

Data Fields
cgc_clock_t source_clock PLL source clock (main oscillator or HOCO)
cgc_pll_div_t divider PLL divider.
cgc_pll_mul_t multiplier PLL multiplier.
cgc_pll_out_div_t out_div_p PLL divisor for output clock P.
cgc_pll_out_div_t out_div_q PLL divisor for output clock Q.
cgc_pll_out_div_t out_div_r PLL divisor for output clock R.

◆ cgc_divider_cfg_t

struct cgc_divider_cfg_t

Clock configuration structure - Used as an input parameter to the cgc_api_t::systemClockSet and cgc_api_t::systemClockGet functions.

◆ cgc_cfg_t

struct cgc_cfg_t

Configuration options.

◆ cgc_clocks_cfg_t

struct cgc_clocks_cfg_t

Clock configuration

Data Fields
cgc_clock_t system_clock System clock source enumeration.
cgc_pll_cfg_t pll_cfg PLL configuration structure.
cgc_pll_cfg_t pll2_cfg PLL2 configuration structure.
cgc_divider_cfg_t divider_cfg Clock dividers structure.
cgc_clock_change_t loco_state State of LOCO.
cgc_clock_change_t moco_state State of MOCO.
cgc_clock_change_t hoco_state State of HOCO.
cgc_clock_change_t mainosc_state State of Main oscillator.
cgc_clock_change_t pll_state State of PLL.
cgc_clock_change_t pll2_state State of PLL2.

◆ cgc_api_t

struct cgc_api_t

CGC functions implemented at the HAL layer follow this API.

Data Fields

fsp_err_t(* open )(cgc_ctrl_t *const p_ctrl, cgc_cfg_t const *const p_cfg)
 
fsp_err_t(* clocksCfg )(cgc_ctrl_t *const p_ctrl, cgc_clocks_cfg_t const *const p_clock_cfg)
 
fsp_err_t(* clockStart )(cgc_ctrl_t *const p_ctrl, cgc_clock_t clock_source, cgc_pll_cfg_t const *const p_pll_cfg)
 
fsp_err_t(* clockStop )(cgc_ctrl_t *const p_ctrl, cgc_clock_t clock_source)
 
fsp_err_t(* clockCheck )(cgc_ctrl_t *const p_ctrl, cgc_clock_t clock_source)
 
fsp_err_t(* systemClockSet )(cgc_ctrl_t *const p_ctrl, cgc_clock_t clock_source, cgc_divider_cfg_t const *const p_divider_cfg)
 
fsp_err_t(* systemClockGet )(cgc_ctrl_t *const p_ctrl, cgc_clock_t *const p_clock_source, cgc_divider_cfg_t *const p_divider_cfg)
 
fsp_err_t(* oscStopDetectEnable )(cgc_ctrl_t *const p_ctrl)
 
fsp_err_t(* oscStopDetectDisable )(cgc_ctrl_t *const p_ctrl)
 
fsp_err_t(* oscStopStatusClear )(cgc_ctrl_t *const p_ctrl)
 
fsp_err_t(* callbackSet )(cgc_ctrl_t *const p_api_ctrl, void(*p_callback)(cgc_callback_args_t *), void const *const p_context, cgc_callback_args_t *const p_callback_memory)
 
fsp_err_t(* close )(cgc_ctrl_t *const p_ctrl)
 

Field Documentation

◆ open

fsp_err_t(* cgc_api_t::open) (cgc_ctrl_t *const p_ctrl, cgc_cfg_t const *const p_cfg)

Initial configuration

Implemented as
Parameters
[in]p_ctrlPointer to instance control block
[in]p_cfgPointer to configuration

◆ clocksCfg

fsp_err_t(* cgc_api_t::clocksCfg) (cgc_ctrl_t *const p_ctrl, cgc_clocks_cfg_t const *const p_clock_cfg)

Configure all system clocks.

Implemented as
Parameters
[in]p_ctrlPointer to instance control block
[in]p_clock_cfgPointer to desired configuration of system clocks

◆ clockStart

fsp_err_t(* cgc_api_t::clockStart) (cgc_ctrl_t *const p_ctrl, cgc_clock_t clock_source, cgc_pll_cfg_t const *const p_pll_cfg)

Start a clock.

Implemented as
Parameters
[in]p_ctrlPointer to instance control block
[in]clock_sourceClock source to start
[in]p_pll_cfgPointer to PLL configuration, can be NULL if clock_source is not CGC_CLOCK_PLL or CGC_CLOCK_PLL2

◆ clockStop

fsp_err_t(* cgc_api_t::clockStop) (cgc_ctrl_t *const p_ctrl, cgc_clock_t clock_source)

Stop a clock.

Implemented as
Parameters
[in]p_ctrlPointer to instance control block
[in]clock_sourceThe clock source to stop

◆ clockCheck

fsp_err_t(* cgc_api_t::clockCheck) (cgc_ctrl_t *const p_ctrl, cgc_clock_t clock_source)

Check the stability of the selected clock.

Implemented as
Parameters
[in]p_ctrlPointer to instance control block
[in]clock_sourceWhich clock source to check for stability

◆ systemClockSet

fsp_err_t(* cgc_api_t::systemClockSet) (cgc_ctrl_t *const p_ctrl, cgc_clock_t clock_source, cgc_divider_cfg_t const *const p_divider_cfg)

Set the system clock.

Implemented as
Parameters
[in]p_ctrlPointer to instance control block
[in]clock_sourceClock source to set as system clock
[in]p_divider_cfgPointer to the clock divider configuration

◆ systemClockGet

fsp_err_t(* cgc_api_t::systemClockGet) (cgc_ctrl_t *const p_ctrl, cgc_clock_t *const p_clock_source, cgc_divider_cfg_t *const p_divider_cfg)

Get the system clock information.

Implemented as
Parameters
[in]p_ctrlPointer to instance control block
[out]p_clock_sourceReturns the current system clock
[out]p_divider_cfgReturns the current system clock dividers

◆ oscStopDetectEnable

fsp_err_t(* cgc_api_t::oscStopDetectEnable) (cgc_ctrl_t *const p_ctrl)

Enable and optionally register a callback for Main Oscillator stop detection.

Implemented as
Parameters
[in]p_ctrlPointer to instance control block
[in]p_callbackCallback function that will be called by the NMI interrupt when an oscillation stop is detected. If the second argument is "false", then this argument can be NULL.
[in]enableEnable/disable Oscillation Stop Detection

◆ oscStopDetectDisable

fsp_err_t(* cgc_api_t::oscStopDetectDisable) (cgc_ctrl_t *const p_ctrl)

Disable Main Oscillator stop detection.

Implemented as
Parameters
[in]p_ctrlPointer to instance control block

◆ oscStopStatusClear

fsp_err_t(* cgc_api_t::oscStopStatusClear) (cgc_ctrl_t *const p_ctrl)

Clear the oscillator stop detection flag.

Implemented as
Parameters
[in]p_ctrlPointer to instance control block

◆ callbackSet

fsp_err_t(* cgc_api_t::callbackSet) (cgc_ctrl_t *const p_api_ctrl, void(*p_callback)(cgc_callback_args_t *), void const *const p_context, cgc_callback_args_t *const p_callback_memory)

Specify callback function and optional context pointer and working memory pointer.

Implemented as
Parameters
[in]p_ctrlPointer to the CGC control block.
[in]p_callbackCallback function
[in]p_contextPointer to send to callback function
[in]p_working_memoryPointer to volatile memory where callback structure can be allocated. Callback arguments allocated here are only valid during the callback.

◆ close

fsp_err_t(* cgc_api_t::close) (cgc_ctrl_t *const p_ctrl)

Close the CGC driver.

Implemented as
Parameters
[in]p_ctrlPointer to instance control block

◆ cgc_instance_t

struct cgc_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
cgc_ctrl_t * p_ctrl Pointer to the control structure for this instance.
cgc_cfg_t const * p_cfg Pointer to the configuration structure for this instance.
cgc_api_t const * p_api Pointer to the API structure for this instance.

Typedef Documentation

◆ cgc_ctrl_t

typedef void cgc_ctrl_t

CGC control block. Allocate an instance specific control block to pass into the CGC API calls.

Implemented as

Enumeration Type Documentation

◆ cgc_event_t

Events that can trigger a callback function

Enumerator
CGC_EVENT_OSC_STOP_DETECT 

Oscillator stop detection has caused the event.

◆ cgc_clock_t

System clock source identifiers - The source of ICLK, BCLK, FCLK, PCLKS A-D and UCLK prior to the system clock divider

Enumerator
CGC_CLOCK_HOCO 

The high speed on chip oscillator.

CGC_CLOCK_MOCO 

The middle speed on chip oscillator.

CGC_CLOCK_LOCO 

The low speed on chip oscillator.

CGC_CLOCK_MAIN_OSC 

The main oscillator.

CGC_CLOCK_SUBCLOCK 

The subclock oscillator.

CGC_CLOCK_PLL 

The PLL oscillator.

CGC_CLOCK_PLL2 

The PLL2 oscillator.

◆ cgc_pll_div_t

PLL divider values

Enumerator
CGC_PLL_DIV_1 

PLL divider of 1.

CGC_PLL_DIV_2 

PLL divider of 2.

CGC_PLL_DIV_3 

PLL divider of 3 (S7, S5 only)

CGC_PLL_DIV_4 

PLL divider of 4 (S3 only)

◆ cgc_pll_out_div_t

PLL clock output divisor.

Enumerator
CGC_PLL_OUT_DIV_2 

PLL output clock divided by 2.

CGC_PLL_OUT_DIV_3 

PLL output clock divided by 3.

CGC_PLL_OUT_DIV_4 

PLL output clock divided by 4.

CGC_PLL_OUT_DIV_5 

PLL output clock divided by 5.

CGC_PLL_OUT_DIV_6 

PLL output clock divided by 6.

CGC_PLL_OUT_DIV_8 

PLL output clock divided by 8.

CGC_PLL_OUT_DIV_9 

PLL output clock divided by 9.

CGC_PLL_OUT_DIV_16 

PLL output clock divided by 16.

◆ cgc_sys_clock_div_t

System clock divider vlues - The individually selectable divider of each of the system clocks, ICLK, BCLK, FCLK, PCLKS A-D.

Enumerator
CGC_SYS_CLOCK_DIV_1 

System clock divided by 1.

CGC_SYS_CLOCK_DIV_2 

System clock divided by 2.

CGC_SYS_CLOCK_DIV_4 

System clock divided by 4.

CGC_SYS_CLOCK_DIV_8 

System clock divided by 8.

CGC_SYS_CLOCK_DIV_16 

System clock divided by 16.

CGC_SYS_CLOCK_DIV_32 

System clock divided by 32.

CGC_SYS_CLOCK_DIV_64 

System clock divided by 64.

◆ cgc_usb_clock_div_t

USB clock divider values

Enumerator
CGC_USB_CLOCK_DIV_3 

Divide USB source clock by 3.

CGC_USB_CLOCK_DIV_4 

Divide USB source clock by 4.

CGC_USB_CLOCK_DIV_5 

Divide USB source clock by 5.

◆ cgc_clock_change_t

Clock options

Enumerator
CGC_CLOCK_CHANGE_START 

Start the clock.

CGC_CLOCK_CHANGE_STOP 

Stop the clock.

CGC_CLOCK_CHANGE_NONE 

No change to the clock.