SysClk (System Clock)

General Description

The System Clock (SysClk) driver contains the API for configuring system and peripheral clocks.

The functions and other declarations used in this driver are in cy_sysclk.h. You can include cy_pdl.h to get access to all functions and declarations in the PDL.

Firmware uses the API to configure, enable, or disable a clock.

The clock system includes a variety of resources that can vary per device, including:

• Internal clock sources such as internal oscillators
• External clock sources such as crystal oscillators or a signal on an I/O pin
• Generated clocks such as an FLL, a PLL, and peripheral clocks

Consult the Technical Reference Manual for your device for details of the clock system.

The PDL defines clock system capabilities in:
devices/include/<series>_config.h. (E.g. devices/include/psoc6_01_config.h). User-configurable clock speeds are defined in the file system_<series>.h.

As an illustration of the clocking system, the following diagram shows the PSoC 63 series clock tree. The actual tree may vary depending on the device series. Consult the Technical Reference Manual for your device for details.

The sysclk driver supports multiple peripheral clocks, as well as the fast clock, slow clock, backup domain clock, timer clock, and pump clock. The API for any given clock contains the functions to manage that clock. Functions for clock measurement and trimming are also provided.

Configuration Considerations

The availability of clock functions depend on the availability of the chip resources that support those functions. Consult the device TRM before attempting to use these functions. For PSoC 64 devices the clocks configurations are restricted and limited. Refer to the PRA driver, and the TRM and datasheet for details.

Warning

On the diagram above, the yellow muxes are glitch-safe. All glitch-safe mux transitions take four cycles of the source clock. It is not allowed to turn off the source clock during that time.

PSoC 6 power modes limit the maximum clock frequency. Refer to the SysPm driver and the TRM for details.

More Information

Refer to the technical reference manual (TRM) and the device datasheet.

MISRA-C Compliance

MISRA Rule	Rule Class (Required/Advisory)	Rule Description	Description of Deviation(s)
10.3	R	A composite expression of the "essentially unsigned" type is being cast to a different type category.	The value got from the bitfield physically cannot exceed the enumeration that describes this bitfield. So, the code is safe by design.
13.7	R	Boolean operations whose result are invariant shall not be permitted.	This math is legacy, preserving the backward compatibility.
16.7	R	The object addressed by the pointer parameter is not modified and so the pointer could be of type 'pointer to const'.	The callback function for system power management (SysPm) must be of generic callback type that contains non-const pointer parameter.

Changelog

Version	Changes	Reason for Change
2.20	Added the assertion mechanism to the following functions: Cy_SysClk_EcoDisable() Cy_SysClk_IloEnable() Cy_SysClk_IloHibernateOn() Cy_SysClk_PiloEnable() Cy_SysClk_PiloDisable() Cy_SysClk_WcoDisable() Cy_SysClk_WcoBypass() Cy_SysClk_ClkFastSetDivider() Cy_SysClk_ClkPeriSetDivider() Cy_SysClk_ClkLfSetSource() Cy_SysClk_ClkTimerSetSource() Cy_SysClk_ClkTimerSetDivider() Cy_SysClk_ClkTimerEnable() Cy_SysClk_ClkTimerDisable() Cy_SysClk_ClkPumpSetSource() Cy_SysClk_ClkPumpSetDivider() Cy_SysClk_ClkPumpEnable() Cy_SysClk_ClkPumpDisable() Cy_SysClk_ClkBakSetSource() Now, the functions described above halt in assertion when a PRA request returns not successful operation. This change is applicable only for the PSoC 64 family devices.	Enhancements for the debugging process.
	Added Cy_SysClk_PiloInitialTrim and Cy_SysClk_PiloUpdateTrimStep functions. Extended the Cy_SysClk_PiloTrim function to use the step-size value calculated for PILO based on the Cy_SysClk_PiloInitialTrim and Cy_SysClk_PiloUpdateTrimStep functions call.	User experience enhancement.
	Added the warning that during a glitch-safe mux, the transition is not allowed to disable the previous clock source. See more info in the Configuration Considerations. Removed Known Issues table.	Documentation updates.
2.10	Updated SysClk functions for PSoC 64 devices. Now the SysClk functions can return PRA driver status value.	The SysClk driver uses the PRA driver to change the protected registers. A SysClk driver function that calls a PRA driver function will return the PRA error status code if the called PRA function returns an error. In these cases, refer to PRA return statuses. Refer to functions description for details.
	Updated the code of Cy_SysClk_ClkPathGetFrequency function.	Make the code more error-resistant to user errors for some corner cases.
	Minor documentation updates.	Documentation enhancement.
2.0	Updated the ECO trimming values calculation algorithm in the Cy_SysClk_EcoConfigure implementation. This change may invalidate the already used crystals, in cases: The crystal frequency is less than 16 MHz. The maximum amplitude (internal calculation value) is less than 0.65 V. For detail, refer the Cy_SysClk_EcoConfigure documentation and the ECO Trimming section of the device TRM.	Enhanced the ECO performance for high-noise conditions that result from simultaneous switching of GPIOs and/or high switching activity on the chip.
1.60	Added the following functions: Cy_SysClk_ExtClkGetFrequency, Cy_SysClk_EcoGetFrequency, Cy_SysClk_ClkPathMuxGetFrequency, Cy_SysClk_ClkPathGetFrequency, Cy_SysClk_IloIsEnabled. Cy_SysClk_PiloIsEnabled, Cy_SysClk_AltHfGetFrequency, Cy_SysClk_ClkHfIsEnabled, Cy_SysClk_ClkTimerIsEnabled, Cy_SysClk_ClkTimerGetFrequency, Cy_SysClk_ClkPumpIsEnabled and Cy_SysClk_ClkPumpGetFrequency.	API enhancement.
1.50	Cy_SysClk_ClkHfGetFrequency is updated to reuse the cy_BleEcoClockFreqHz global system variable.	API enhancement.
1.40.2	Update documentation based on collateral review feedback.	User experience enhancement.
1.40.1	Fix compiler warning.
1.40	Updated the following functions implementation: Cy_SysClk_PllConfigure and Cy_SysClk_PllEnable.	Fixed the Cy_SysClk_PllConfigure API function behaviour when it is called with a bypass mode, Fixed the Cy_SysClk_PllEnable API function behaviour when it is called with a zero timeout.
	Added the following functions: Cy_SysClk_MfoEnable, Cy_SysClk_MfoIsEnabled, Cy_SysClk_MfoDisable, Cy_SysClk_ClkMfEnable, Cy_SysClk_ClkMfIsEnabled, Cy_SysClk_ClkMfDisable, Cy_SysClk_ClkMfGetDivider, Cy_SysClk_ClkMfSetDivider, . Cy_SysClk_ClkMfGetFrequency	New device support.
	Added the following new API functions Cy_SysClk_FllIsEnabled, Cy_SysClk_PllIsEnabled, Cy_SysClk_ExtClkSetFrequency, Cy_SysClk_ClkHfGetFrequency, Cy_SysClk_ClkFastGetFrequency, Cy_SysClk_ClkPeriGetFrequency and Cy_SysClk_ClkSlowGetFrequency	Enhancement based on usability feedback
	Deprecated the following macros: CY_SYSCLK_DIV_ROUND and CY_SYSCLK_DIV_ROUNDUP	Macros were moved into SysLib (System Library)
1.30	Updated the following functions implementation: Cy_SysClk_EcoConfigure and Cy_SysClk_FllConfigure.	Math library dependency is removed, the floating-point math is replaced with integer math.
	Updated the following functions implementation: Cy_SysClk_EcoEnable, Cy_SysClk_EcoGetStatus, Cy_SysClk_FllGetConfiguration and Cy_SysClk_DeepSleepCallback. The Cy_SysClk_DeepSleepCallback now implements all four SysPm callback modes cy_en_syspm_callback_mode_t. The actions that were done in CY_SYSPM_CHECK_READY case are moved to CY_SYSPM_BEFORE_TRANSITION. So the cy_stc_syspm_callback_t::skipMode must be set to 0UL.	Defect fixing.
1.20	Flattened the organization of the driver source code into the single source directory and the single include directory.	Driver library directory-structure simplification.
	Updated Cy_SysClk_FllLocked function description	The SRSS_ver1 HW details clarification
	Removed the following functions: Cy_SysClk_FllLostLock Cy_SysClk_WcoConfigureCsv Cy_SysClk_ClkHfConfigureCsv	No hardware support for the removed functions.
	Added register access layer. Use register access macros instead of direct register access using dereferenced pointers.	Makes register access device-independent, so that the PDL does not need to be recompiled for each supported part number.
1.11	Updated the following functions. Now they use a semaphore when try to read the status or configure the SysClk measurement counters: Cy_SysClk_StartClkMeasurementCounters() Cy_SysClk_ClkMeasurementCountersGetFreq() Now Cy_SysClk_ClkMeasurementCountersGetFreq() returns zero value, if during measurement device was in the Deep Sleep or partially blocking flash operation occurred	Added arbiter mechanism for correct usage of the SysClk measurement counters
1.10.1	Renamed Power Management section to Low Power Callback section	Documentation update and clarification
1.10	Updated FLL parameter calculation	Support low frequency sources
	Added Cy_SysClk_PiloSetTrim() and Cy_SysclkPiloGetTrim() functions	Support PILO manual trims
	Made Cy_SysClk_FllLostLock() function dependent on SRSS v1	Feature is not supported in SRSS v1
	Updated Cy_SysClk_DeepSleepCallback() to save/restore both FLL and PLL settings	The function should return when the lock is established or a timeout has occurred
	General documentation updates
1.0	Initial version

API Reference
	Macros
	General Enumerated Types
	External Clock Source (EXTCLK)
	The External Clock Source (EXTCLK) is a clock source routed into PSoC through a GPIO pin.
	External Crystal Oscillator (ECO)
	The External Crystal Oscillator (ECO) is a clock source that consists of an oscillator circuit that drives an external crystal through its dedicated ECO pins.
	Clock Path Source
	Clock paths are a series of multiplexers that allow a source clock to drive multiple clocking resources down the chain.
	Frequency Locked Loop (FLL)
	The FLL is a clock generation circuit that can be used to produce a higher frequency clock from a reference clock.
	Phase Locked Loop (PLL)
	The PLL is a clock generation circuit that can be used to produce a higher frequency clock from a reference clock.
	Internal Low-Speed Oscillator (ILO)
	The ILO operates with no external components and outputs a stable clock at 32.768 kHz nominal.
	Precision Internal Low-Speed Oscillator (PILO)
	PILO provides a higher accuracy 32.768 kHz clock than the ILO.
	Clock Measurement
	These functions measure the frequency of a specified clock relative to a reference clock.
	Clock Trim (ILO, PILO)
	These functions perform a single trim operation on the ILO or PILO.
	Low Power Callback
	Entering and exiting low power modes require compatible clock configurations to be set before entering low power and restored upon wake-up and exit.
	Watch Crystal Oscillator (WCO)
	The WCO is a highly accurate 32.768 kHz clock source capable of operating in all power modes (excluding the Off mode).
	High-Frequency Clocks
	Multiple high frequency clocks (CLK_HF) are available in the device.
	Fast Clock
	The fast clock drives the "fast" processor (e.g.
	Peripheral Clock
	The peripheral clock is a divided clock of CLK_HF0 (HF Clocks).
	Peripherals Clock Dividers
	There are multiple peripheral clock dividers that, in effect, create multiple separate peripheral clocks.
	Slow Clock
	The slow clock is the source clock for the "slow" processor (e.g.
	Alternative High-Frequency Clock
	In the BLE-enabled PSoC6 devices, the BLE ECO (BLE ECO Clock) clock is connected to the system Alternative High-Frequency Clock input.
	Low-Frequency Clock
	The low-frequency clock is the source clock for the MCWDT (Multi-Counter Watchdog) and can be the source clock for Backup Domain Clock, which drives the RTC (Real-Time Clock).
	Timer Clock
	The timer clock can be a source for the alternative clock driving the SysTick (ARM System Timer).
	Pump Clock
	The pump clock is a clock source used to provide analog precision in low voltage applications.
	Backup Domain Clock
	The backup domain clock drives the RTC (Real-Time Clock).
	Medium Frequency Domain Clock
	The Medium Frequency Domain Clock is present only in SRSS_ver1_3.