cfn_hal_clock.h File Reference

Clock Management HAL API. More...

#include "cfn_hal.h"
#include "cfn_hal_base.h"
#include "cfn_hal_types.h"

Go to the source code of this file.

Data Structures
struct	cfn_hal_clock_config_t
	Clock configuration structure. More...
struct	cfn_hal_clock_phy_t
	Clock hardware physical mapping. More...
struct	cfn_hal_clock_api_s
	Clock Virtual Method Table (VMT). More...

Typedefs
typedef struct cfn_hal_clock_s	cfn_hal_clock_t
typedef struct cfn_hal_clock_api_s	cfn_hal_clock_api_t
typedef void(*	cfn_hal_clock_callback_t) (cfn_hal_clock_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)
	Clock callback signature.

Enumerations
enum	cfn_hal_clock_event_t { CFN_HAL_CLOCK_EVENT_NONE = 0 , CFN_HAL_CLOCK_EVENT_READY = CFN_HAL_BIT(0) }
	Clock nominal event flags. More...
enum	cfn_hal_clock_error_t { CFN_HAL_CLOCK_ERROR_NONE = 0 , CFN_HAL_CLOCK_ERROR_LSE_FAIL = CFN_HAL_BIT(0) , CFN_HAL_CLOCK_ERROR_HSE_FAIL = CFN_HAL_BIT(1) , CFN_HAL_CLOCK_ERROR_GENERAL = CFN_HAL_BIT(2) }
	Clock exception error flags. More...

Functions
	CFN_HAL_VMT_CHECK (struct cfn_hal_clock_api_s)
	CFN_HAL_CREATE_DRIVER_TYPE (clock, cfn_hal_clock_config_t, cfn_hal_clock_api_t, cfn_hal_clock_phy_t, cfn_hal_clock_callback_t)
CFN_HAL_INLINE void	cfn_hal_clock_populate (cfn_hal_clock_t *driver, uint32_t peripheral_id, struct cfn_hal_clock_s *clock, void *dependency, const cfn_hal_clock_api_t *api, const cfn_hal_clock_phy_t *phy, const cfn_hal_clock_config_t *config, cfn_hal_clock_callback_t callback, void *user_arg)
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_config_validate (const cfn_hal_clock_t *driver, const cfn_hal_clock_config_t *config)
	Validates the Clock configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_init (cfn_hal_clock_t *driver)
	Initializes the Clock driver.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_deinit (cfn_hal_clock_t *driver)
	Deinitializes the Clock driver.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_config_set (cfn_hal_clock_t *driver, const cfn_hal_clock_config_t *config)
	Sets the Clock configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_config_get (cfn_hal_clock_t *driver, cfn_hal_clock_config_t *config)
	Gets the current Clock configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_callback_register (cfn_hal_clock_t *driver, const cfn_hal_clock_callback_t callback, void *user_arg)
	Registers a callback for Clock events and errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_power_state_set (cfn_hal_clock_t *driver, cfn_hal_power_state_t state)
	Sets the Clock power state.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_event_enable (cfn_hal_clock_t *driver, uint32_t event_mask)
	Enables one or more Clock nominal events.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_event_disable (cfn_hal_clock_t *driver, uint32_t event_mask)
	Disables one or more Clock nominal events.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_event_get (cfn_hal_clock_t *driver, uint32_t *event_mask)
	Retrieves the current Clock nominal event status.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_error_enable (cfn_hal_clock_t *driver, uint32_t error_mask)
	Enables one or more Clock exception errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_error_disable (cfn_hal_clock_t *driver, uint32_t error_mask)
	Disables one or more Clock exception errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_error_get (cfn_hal_clock_t *driver, uint32_t *error_mask)
	Retrieves the current Clock exception error status.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_suspend_tick (cfn_hal_clock_t *driver)
	Suspends the system tick (e.g. before entering sleep).
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_resume_tick (cfn_hal_clock_t *driver)
	Resumes the system tick (e.g. after waking up).
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_get_system_freq (cfn_hal_clock_t *driver, uint32_t *freq_hz)
	Gets the current main system clock frequency.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_get_peripheral_freq (cfn_hal_clock_t *driver, uint32_t peripheral_id, uint32_t *freq_hz)
	Gets the clock frequency for a specific peripheral domain.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_enable_gate (cfn_hal_clock_t *driver, uint32_t peripheral_id)
	Enables the clock gate for a specific peripheral.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_clock_disable_gate (cfn_hal_clock_t *driver, uint32_t peripheral_id)
	Disables the clock gate for a specific peripheral.
cfn_hal_error_code_t	cfn_hal_clock_construct (cfn_hal_clock_t *driver, const cfn_hal_clock_config_t *config, const cfn_hal_clock_phy_t *phy, struct cfn_hal_clock_s *clock, void *dependency, cfn_hal_clock_callback_t callback, void *user_arg)
cfn_hal_error_code_t	cfn_hal_clock_destruct (cfn_hal_clock_t *driver)

Detailed Description

Clock Management HAL API.

Copyright (c) 2026 Hisham Moussa Daou https://www.whileone.me

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Typedef Documentation

cfn_hal_clock_api_t

typedef struct cfn_hal_clock_api_s cfn_hal_clock_api_t

cfn_hal_clock_callback_t

typedef void(* cfn_hal_clock_callback_t) (cfn_hal_clock_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)

Clock callback signature.

Parameters

driver	Pointer to the Clock driver instance.
event_mask	Mask of triggered nominal events.
error_mask	Mask of triggered exception errors.
user_arg	User-defined argument passed during registration.

cfn_hal_clock_t

typedef struct cfn_hal_clock_s cfn_hal_clock_t

Enumeration Type Documentation

cfn_hal_clock_error_t

enum cfn_hal_clock_error_t

Clock exception error flags.

Enumerator
CFN_HAL_CLOCK_ERROR_NONE
CFN_HAL_CLOCK_ERROR_LSE_FAIL	Low Speed External oscillator failure
CFN_HAL_CLOCK_ERROR_HSE_FAIL	High Speed External oscillator failure
CFN_HAL_CLOCK_ERROR_GENERAL	General clock hardware error

cfn_hal_clock_event_t

enum cfn_hal_clock_event_t

Clock nominal event flags.

Enumerator
CFN_HAL_CLOCK_EVENT_NONE
CFN_HAL_CLOCK_EVENT_READY	Clock source is stable and ready

Function Documentation

cfn_hal_clock_callback_register()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_callback_register	(	cfn_hal_clock_t *	driver,
		const cfn_hal_clock_callback_t	callback,
		void *	user_arg
	)

Registers a callback for Clock events and errors.

Parameters

driver	Pointer to the Clock driver instance.
callback	The callback function to register.
user_arg	User-defined argument passed to the callback.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_config_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_config_get	(	cfn_hal_clock_t *	driver,
		cfn_hal_clock_config_t *	config
	)

Gets the current Clock configuration.

Parameters

driver	Pointer to the Clock driver instance.
config	[out] Pointer to store the configuration.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_config_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_config_set	(	cfn_hal_clock_t *	driver,
		const cfn_hal_clock_config_t *	config
	)

Sets the Clock configuration.

Parameters

driver	Pointer to the Clock driver instance.
config	Pointer to the configuration structure.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_config_validate()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_config_validate	(	const cfn_hal_clock_t *	driver,
		const cfn_hal_clock_config_t *	config
	)

Validates the Clock configuration.

Parameters

driver	Pointer to the CLOCK driver instance.
config	Pointer to the configuration structure.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_construct()

cfn_hal_error_code_t cfn_hal_clock_construct	(	cfn_hal_clock_t *	driver,
		const cfn_hal_clock_config_t *	config,
		const cfn_hal_clock_phy_t *	phy,
		struct cfn_hal_clock_s *	clock,
		void *	dependency,
		cfn_hal_clock_callback_t	callback,
		void *	user_arg
	)

cfn_hal_clock_deinit()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_deinit

(

cfn_hal_clock_t *

driver

)

Deinitializes the Clock driver.

Parameters

driver

Pointer to the Clock driver instance.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_destruct()

cfn_hal_error_code_t cfn_hal_clock_destruct

(

cfn_hal_clock_t *

driver

)

cfn_hal_clock_disable_gate()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_disable_gate	(	cfn_hal_clock_t *	driver,
		uint32_t	peripheral_id
	)

Disables the clock gate for a specific peripheral.

Parameters

driver	Pointer to the Clock driver instance.
peripheral_id	ID or FourCC of the target peripheral.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_enable_gate()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_enable_gate	(	cfn_hal_clock_t *	driver,
		uint32_t	peripheral_id
	)

Enables the clock gate for a specific peripheral.

Parameters

driver	Pointer to the Clock driver instance.
peripheral_id	ID or FourCC of the target peripheral.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_error_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_error_disable	(	cfn_hal_clock_t *	driver,
		uint32_t	error_mask
	)

Disables one or more Clock exception errors.

Parameters

driver	Pointer to the Clock driver instance.
error_mask	Mask of errors to disable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_error_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_error_enable	(	cfn_hal_clock_t *	driver,
		uint32_t	error_mask
	)

Enables one or more Clock exception errors.

Parameters

driver	Pointer to the Clock driver instance.
error_mask	Mask of errors to enable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_error_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_error_get	(	cfn_hal_clock_t *	driver,
		uint32_t *	error_mask
	)

Retrieves the current Clock exception error status.

Parameters

driver	Pointer to the Clock driver instance.
error_mask	[out] Pointer to store the error mask.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_event_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_event_disable	(	cfn_hal_clock_t *	driver,
		uint32_t	event_mask
	)

Disables one or more Clock nominal events.

Parameters

driver	Pointer to the Clock driver instance.
event_mask	Mask of events to disable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_event_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_event_enable	(	cfn_hal_clock_t *	driver,
		uint32_t	event_mask
	)

Enables one or more Clock nominal events.

Parameters

driver	Pointer to the Clock driver instance.
event_mask	Mask of events to enable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_event_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_event_get	(	cfn_hal_clock_t *	driver,
		uint32_t *	event_mask
	)

Retrieves the current Clock nominal event status.

Parameters

driver	Pointer to the Clock driver instance.
event_mask	[out] Pointer to store the event mask.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_get_peripheral_freq()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_get_peripheral_freq	(	cfn_hal_clock_t *	driver,
		uint32_t	peripheral_id,
		uint32_t *	freq_hz
	)

Gets the clock frequency for a specific peripheral domain.

Parameters

driver	Pointer to the Clock driver instance.
peripheral_id	ID or FourCC of the target peripheral.
freq_hz	[out] Pointer to store the frequency in Hz.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_get_system_freq()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_get_system_freq	(	cfn_hal_clock_t *	driver,
		uint32_t *	freq_hz
	)

Gets the current main system clock frequency.

Parameters

driver	Pointer to the Clock driver instance.
freq_hz	[out] Pointer to store the frequency in Hz.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_init()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_init

(

cfn_hal_clock_t *

driver

)

Initializes the Clock driver.

Parameters

driver

Pointer to the Clock driver instance.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_populate()

CFN_HAL_INLINE void cfn_hal_clock_populate	(	cfn_hal_clock_t *	driver,
		uint32_t	peripheral_id,
		struct cfn_hal_clock_s *	clock,
		void *	dependency,
		const cfn_hal_clock_api_t *	api,
		const cfn_hal_clock_phy_t *	phy,
		const cfn_hal_clock_config_t *	config,
		cfn_hal_clock_callback_t	callback,
		void *	user_arg
	)

cfn_hal_clock_power_state_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_power_state_set	(	cfn_hal_clock_t *	driver,
		cfn_hal_power_state_t	state
	)

Sets the Clock power state.

Parameters

driver	Pointer to the Clock driver instance.
state	Target power state.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_resume_tick()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_resume_tick

(

cfn_hal_clock_t *

driver

)

Resumes the system tick (e.g. after waking up).

Parameters

driver

Pointer to the Clock driver instance.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_clock_suspend_tick()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_clock_suspend_tick

(

cfn_hal_clock_t *

driver

)

Suspends the system tick (e.g. before entering sleep).

Parameters

driver

Pointer to the Clock driver instance.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

CFN_HAL_CREATE_DRIVER_TYPE()

CFN_HAL_CREATE_DRIVER_TYPE	(	clock	,
		cfn_hal_clock_config_t	,
		cfn_hal_clock_api_t	,
		cfn_hal_clock_phy_t	,
		cfn_hal_clock_callback_t
	)

CFN_HAL_VMT_CHECK()

CFN_HAL_VMT_CHECK

(

struct cfn_hal_clock_api_s

)