MT2523 API Reference  LinkIt SDK v4
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.

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 clock 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 clock 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 clock 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 clock might not turn off and will result in more power consumption.
  5. Use hal_clock_is_enabled() to check and verify whether the corresponding clock 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
 
 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_idis 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_idis 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_idis 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.