S32 SDK
Clock Manager

Detailed Description

This module covers the clock management API and clock related functionality.

This section describes the programming interface of the clock_manager driver. Clock_manager achieves its functionality by configuring the hardware modules involved in clock distribution and management.

Notes

Current implementation assumes that the clock configurations are valid and are applied in a valid sequence. Mainly this means that the configuration doesn't reinitialize the clock used as the system clock.

Code Example

This is an example for switching between two configurations:

CLOCK_SYS_Init(g_clockManConfigsArr,
CLOCK_MANAGER_CONFIG_CNT,
g_clockManCallbacksArr,
CLOCK_MANAGER_CALLBACK_CNT);

Modules

 Clock Manager Driver
 This module covers the device-specific clock_manager functionality implemented for S32K144 SOC.
 
 Clock_manager_s32k1xx
 

Data Structures

struct  clock_manager_user_config_t
 Clock configuration structure. Implements clock_manager_user_config_t_Class. More...
 
struct  clock_notify_struct_t
 Clock notification structure passed to clock callback function. Implements clock_notify_struct_t_Class. More...
 
struct  clock_manager_callback_user_config_t
 Structure for callback function and its parameter. Implements clock_manager_callback_user_config_t_Class. More...
 
struct  clock_manager_state_t
 Clock manager state structure. Implements clock_manager_state_t_Class. More...
 

Typedefs

typedef status_t(* clock_manager_callback_t) (clock_notify_struct_t *notify, void *callbackData)
 Type of clock callback functions. More...
 

Enumerations

enum  clock_manager_notify_t { CLOCK_MANAGER_NOTIFY_RECOVER = 0x00U, CLOCK_MANAGER_NOTIFY_BEFORE = 0x01U, CLOCK_MANAGER_NOTIFY_AFTER = 0x02U }
 The clock notification type. Implements clock_manager_notify_t_Class. More...
 
enum  clock_manager_callback_type_t { CLOCK_MANAGER_CALLBACK_BEFORE = 0x01U, CLOCK_MANAGER_CALLBACK_AFTER = 0x02U, CLOCK_MANAGER_CALLBACK_BEFORE_AFTER = 0x03U }
 The callback type, indicates what kinds of notification this callback handles. Implements clock_manager_callback_type_t_Class. More...
 
enum  clock_manager_policy_t { CLOCK_MANAGER_POLICY_AGREEMENT, CLOCK_MANAGER_POLICY_FORCIBLE }
 Clock transition policy. Implements clock_manager_policy_t_Class. More...
 

Dynamic clock setting

status_t CLOCK_SYS_Init (clock_manager_user_config_t const **clockConfigsPtr, uint8_t configsNumber, clock_manager_callback_user_config_t **callbacksPtr, uint8_t callbacksNumber)
 Install pre-defined clock configurations. More...
 
status_t CLOCK_SYS_UpdateConfiguration (uint8_t targetConfigIndex, clock_manager_policy_t policy)
 Set system clock configuration according to pre-defined structure. More...
 
status_t CLOCK_SYS_SetConfiguration (clock_manager_user_config_t const *config)
 Set system clock configuration. More...
 
uint8_t CLOCK_SYS_GetCurrentConfiguration (void)
 Get current system clock configuration. More...
 
clock_manager_callback_user_config_tCLOCK_SYS_GetErrorCallback (void)
 Get the callback which returns error in last clock switch. More...
 
status_t CLOCK_SYS_GetFreq (clock_names_t clockName, uint32_t *frequency)
 Gets the clock frequency for a specific clock name. More...
 

Typedef Documentation

typedef status_t(* clock_manager_callback_t) (clock_notify_struct_t *notify, void *callbackData)

Type of clock callback functions.

Definition at line 135 of file clock_manager.h.

Enumeration Type Documentation

The callback type, indicates what kinds of notification this callback handles. Implements clock_manager_callback_type_t_Class.

Enumerator
CLOCK_MANAGER_CALLBACK_BEFORE 

Callback handles BEFORE notification.

CLOCK_MANAGER_CALLBACK_AFTER 

Callback handles AFTER notification.

CLOCK_MANAGER_CALLBACK_BEFORE_AFTER 

Callback handles BEFORE and AFTER notification

Definition at line 104 of file clock_manager.h.

The clock notification type. Implements clock_manager_notify_t_Class.

Enumerator
CLOCK_MANAGER_NOTIFY_RECOVER 

Notify IP to recover to previous work state.

CLOCK_MANAGER_NOTIFY_BEFORE 

Notify IP that system will change clock setting.

CLOCK_MANAGER_NOTIFY_AFTER 

Notify IP that have changed to new clock setting.

Definition at line 93 of file clock_manager.h.

Clock transition policy. Implements clock_manager_policy_t_Class.

Enumerator
CLOCK_MANAGER_POLICY_AGREEMENT 

Clock transfers gracefully.

CLOCK_MANAGER_POLICY_FORCIBLE 

Clock transfers forcefully.

Definition at line 115 of file clock_manager.h.

Function Documentation

uint8_t CLOCK_SYS_GetCurrentConfiguration ( void  )

Get current system clock configuration.

Returns
Current clock configuration index.

Definition at line 208 of file clock_manager.c.

clock_manager_callback_user_config_t* CLOCK_SYS_GetErrorCallback ( void  )

Get the callback which returns error in last clock switch.

When graceful policy is used, if some IP is not ready to change clock setting, the callback will return error and system stay in current configuration. Applications can use this function to check which IP callback returns error.

Returns
Pointer to the callback which returns error.

Definition at line 220 of file clock_manager.c.

status_t CLOCK_SYS_GetFreq ( clock_names_t  clockName,
uint32_t *  frequency 
)

Gets the clock frequency for a specific clock name.

This function checks the current clock configurations and then calculates the clock frequency for a specific clock name defined in clock_names_t. The SCG must be properly configured before using this function. See the reference manual for supported clock names for different chip families. The returned value is in Hertz. If it cannot find the clock name or the name is not supported for a specific chip family, it returns an STATUS_UNSUPPORTED. If frequency is required for a peripheral and the module is not clocked, then STATUS_MCU_GATED_OFF status is returned. Frequency is returned if a valid address is provided. If frequency is required for a peripheral that doesn't support functional clock, the zero value is provided.

Parameters
[in]clockNameClock names defined in clock_names_t
[out]frequencyReturned clock frequency value in Hertz
Returns
status Error code defined in status_t

Definition at line 797 of file clock_S32K1xx.c.

status_t CLOCK_SYS_Init ( clock_manager_user_config_t const **  clockConfigsPtr,
uint8_t  configsNumber,
clock_manager_callback_user_config_t **  callbacksPtr,
uint8_t  callbacksNumber 
)

Install pre-defined clock configurations.

This function installs the pre-defined clock configuration table to clock manager.

Parameters
[in]clockConfigsPtrPointer to the clock configuration table.
[in]configsNumberNumber of clock configurations in table.
[in]callbacksPtrPointer to the callback configuration table.
[in]callbacksNumberNumber of callback configurations in table.
Returns
Error code.

Definition at line 57 of file clock_manager.c.

status_t CLOCK_SYS_SetConfiguration ( clock_manager_user_config_t const *  config)

Set system clock configuration.

This function sets the system to target configuration, it only sets the clock modules registers for clock mode change, but not send notifications to drivers. This function is different by different SoCs.

Parameters
[in]configTarget configuration.
Returns
Error code.
Note
If external clock is used in the target mode, please make sure it is enabled, for example, if the external oscillator is used, please setup EREFS/HGO correctly and make sure OSCINIT is set.

Definition at line 244 of file clock_S32K1xx.c.

status_t CLOCK_SYS_UpdateConfiguration ( uint8_t  targetConfigIndex,
clock_manager_policy_t  policy 
)

Set system clock configuration according to pre-defined structure.

This function sets system to target clock configuration; before transition, clock manager will send notifications to all drivers registered to the callback table. When graceful policy is used, if some drivers are not ready to change, clock transition will not occur, all drivers still work in previous configuration and error is returned. When forceful policy is used, all drivers should stop work and system changes to new clock configuration.

Parameters
[in]targetConfigIndexIndex of the clock configuration.
[in]policyTransaction policy, graceful or forceful.
Returns
Error code.
Note
If external clock is used in the target mode, please make sure it is enabled, for example, if the external oscillator is used, please setup EREFS/HGO correctly and make sure OSCINIT is set.

Definition at line 90 of file clock_manager.c.