CLOCK

This section introduces the Clock APIs including terms and acronyms, Clock function groups, enums, structures and functions. More...

Overview

This section introduces the Clock APIs including terms and acronyms, Clock function groups, enums, structures and functions.

The Clock Manager provides APIs to manage the clocks and the Clock Gating (CG), such as enabling and disabling the clock through the CG and querying the clock status.

Terms and acronyms

The following provides descriptions of the terms commonly used in the Clock driver.

Terms	Details
CG	Clock gating, applied to disable the clock.
PLL	Phase-locked loop.

Clock configuration

The clock configuration is chipset dependent and more details can be found in reference manual of the chipset.

• Digitally Controlled Crystal oscillator (DCXO), and/or RC oscillator.
• PLLs to generate clocks at specific frequencies, such as use USB PLL (UPLL) in MediaTek MT2523 chipset to generate 312MHz frequency clock.
• Dividers and multiplexers (MUXs) to switch clock source/frequency for system and peripherals. The essential clock configuration includes settings for MCU, BUS, serial flash, and more.
• CGs for turning on/off the clock to corresponding modules. Please refer to HAL_CLOCK_CG_ID descriptions.

The PLL, divider and MUX settings are configured in the booting stage. The Clock API is for turning on/off the clock gates and is mainly used in the peripheral drivers.

How to use this driver

Call hal_clock_init() to initialize the clock only once before using any Clock API, otherwise the return status of the functions hal_clock_enable() and hal_clock_disable() will be HAL_CLOCK_STATUS_UNINITIALIZED.

The hal_clock_enable() and hal_clock_disable() APIs contain a reference counter that counts the number of times the API is called to support multiple users.

The Clock API supports sharing a single clock with multiple users.

Consider the following suggestions when calling hal_clock_enable() and hal_clock_disable():

1. Each CG has its own counter for reference counting. The default value is zero.
2. For each call of the hal_clock_enable() API, the corresponding reference counter increases by 1.
   • Only when the counter value changes from 0 to 1, the corresponding register value is modified and the CG is enabled.
   • In all other cases, calling hal_clock_enable() only increases the counter value.
3. When hal_clock_disable() is called, the corresponding reference counter decreases by 1.
   • Only when the counter value changes from 1 to 0, the corresponding register value is modified and the CG is disabled.
   • In all other cases, calling hal_clock_disable() decreases the counter value.
4. The hal_clock_enable() and hal_clock_disable() APIs should be used in pair. Otherwise the CG might not turn off and will result in more power consumption.
5. Use hal_clock_is_enabled() to check and verify whether the corresponding CG is enabled or disabled.

Functions
hal_clock_status_t	hal_clock_init (void)
	This function initializes the clock driver and CG before using any Clock API. More...
hal_clock_status_t	hal_clock_enable (hal_clock_cg_id clock_id)
	This function enables a specific CG clock. More...
hal_clock_status_t	hal_clock_disable (hal_clock_cg_id clock_id)
	This function disables a specific CG clock. More...
bool	hal_clock_is_enabled (hal_clock_cg_id clock_id)
	This function queries the status of a specific CG clock. More...
uint32_t	hal_clock_get_mcu_clock_frequency (void)
	This function gets the MCU clock frequency. More...

Modules
	Clock Gate
	Enum

Function Documentation

hal_clock_status_t hal_clock_disable

(

hal_clock_cg_id

clock_id

)

This function disables a specific CG clock.

Parameters

[in]

clock_id

is a unique clock identifier.

Returns

HAL_CLOCK_STATUS_OK, if the operation completed successfully.
HAL_CLOCK_STATUS_UNINITIALIZED, if the clock driver is not initialized.
HAL_CLOCK_STATUS_INVALID_PARAMETER, if the input parameter is invalid.
HAL_CLOCK_STATUS_ERROR, if the clock function detected a common error.

hal_clock_status_t hal_clock_enable

(

hal_clock_cg_id

clock_id

)

This function enables a specific CG clock.

Parameters

[in]

clock_id

is a unique clock identifier.

Returns

HAL_CLOCK_STATUS_OK, if the operation completed successfully.
HAL_CLOCK_STATUS_UNINITIALIZED, if the clock driver is not initialized.
HAL_CLOCK_STATUS_INVALID_PARAMETER, if the input parameter is invalid.
HAL_CLOCK_STATUS_ERROR, if the clock function detected a common error.

uint32_t hal_clock_get_mcu_clock_frequency

(

void

)

This function gets the MCU clock frequency.

Returns

the MCU clock frequency in Hz.

hal_clock_status_t hal_clock_init

(

void

)

This function initializes the clock driver and CG before using any Clock API.

Returns

HAL_CLOCK_STATUS_OK, if the operation completed successfully.
HAL_CLOCK_STATUS_UNINITIALIZED, if the clock driver is not initialized.
HAL_CLOCK_STATUS_INVALID_PARAMETER, if the input parameter is invalid.
HAL_CLOCK_STATUS_ERROR, if the clock function detected a common error.

bool hal_clock_is_enabled

(

hal_clock_cg_id

clock_id

)

This function queries the status of a specific CG clock.

Parameters

[in]

clock_id

is a unique clock identifier.

Returns

true, if the specified clock is enabled.
false, if the specified clock is disabled or the clock driver is not initialized.