Clock Manager Service

Clock Manager. More...

Files
file	sys_clock_mgr.h
	Clock Manager header file.

Functions
void	cm_sys_clk_init (sys_clk_t type)
	Initialize clocks after power-up. More...
void	cm_sys_clk_set_priority (sys_clk_t *sys_clk_prio_array)
	Set the system clock priority. More...
cm_sys_clk_status_t	cm_sys_clk_request (sys_clk_t type)
	Request for system clock switch. More...
cm_sys_clk_status_t	cm_sys_clk_release (sys_clk_t type)
	Restores the system clock. It terminates a matching request. More...
void	cm_apb_set_clock_divider (apb_div_t div)
	Change the divider of the AMBA Peripheral Bus clock. More...
bool	cm_ahb_set_clock_divider (ahb_div_t div)
	Change the divider of the AMBA High speed Bus clock. More...
sys_clk_t	cm_sys_clk_get (void)
	Returns the sys_clk that the system uses at that moment. More...
sys_clk_t	cm_sys_clk_get_fromISR (void)
	Returns the sys_clk that the system uses at that moment (interrupt safe version). More...
apb_div_t	cm_apb_get_clock_divider (void)
	Returns the AMBA Peripheral Bus clock divider. More...
ahb_div_t	cm_ahb_get_clock_divider (void)
	Returns the AMBA High speed Bus clock divider. More...
cpu_clk_t	cm_cpu_clk_get (void)
	Returns the CPU clock frequency. More...
cpu_clk_t	cm_cpu_clk_get_fromISR (void)
	Returns the CPU clock frequency (interrupt safe). More...
void	cm_calibrate_rclp (void)
	Calibrate RCLP.
void	cm_calibrate_rc32m (void)
	Calibrate RC32M.
void	cm_wait_xtalm_ready (void)
	Block until the fast XTAL clock (XTALxxM) is ready. If the fast XTAL clock (XTALxxM) is running then the function exits immediately. More...
void	cm_wait_dblr_ready (void)
	Block until the Doubler is ready. More...
__RETAINED_CODE bool	cm_poll_xtalm_ready (void)
	Check if the fast XTAL clock (XTALxxM) is ready. More...
void	cm_enable_xtalm (void)
	Start the fast XTAL clock (XTALxxM) More...
__RETAINED_CODE void	cm_sys_clk_sleep (bool entering_sleep)
	Set the system clock (unprotected). More...
__RETAINED_CODE void	cm_halt_until_xtalm_ready (void)
	Halt until the fast XTAL clock (XTALxxM) has settled. More...
void	cm_register_xtal_ready_callback (void(*cb)(void))
	Register a callback function to be called then XTAL32M is ready. More...
__RETAINED_CODE void	cm_halt_until_sysclk_ready (void)
	Halt until system clock (either PLL or XTAL32M) is ready. More...

Detailed Description

Clock Manager.

Function Documentation

cm_ahb_get_clock_divider()

ahb_div_t cm_ahb_get_clock_divider

(

void

)

Returns the AMBA High speed Bus clock divider.

Returns

The hclk being used.

Warning

It may block. It cannot be called from Interrupt Context.

cm_ahb_set_clock_divider()

bool cm_ahb_set_clock_divider

(

ahb_div_t

div

)

Change the divider of the AMBA High speed Bus clock.

The frequency of the AHB clock is (system_clock / (1 << cm_ahbclk)). Note: if the SysTick runs then it is the dg_configABORT_IF_SYSTICK_CLK_ERR setting that controls whether the switch will be aborted or not.

Parameters

[in]

div

The new value of the AHB divider.

Returns

True if the divider was changed to the requested value, else false.

Warning

It may block. It cannot be called from Interrupt Context.

cm_apb_get_clock_divider()

apb_div_t cm_apb_get_clock_divider

(

void

)

Returns the AMBA Peripheral Bus clock divider.

Returns

The pclk being used.

Warning

It may block. It cannot be called from Interrupt Context.

cm_apb_set_clock_divider()

void cm_apb_set_clock_divider

(

apb_div_t

div

)

Change the divider of the AMBA Peripheral Bus clock.

The frequency of the APB clock is (system_clock / (1 << cm_ahbclk)) / (1 << cm_apbclk).

Parameters

[in]

div

The new value of the APB divider.

Warning

It may block. It cannot be called from Interrupt Context.

cm_cpu_clk_get()

cpu_clk_t cm_cpu_clk_get

(

void

)

Returns the CPU clock frequency.

Returns

The CPU clock being used.

Warning

Any restrictions of the cm_sys_clk_get() and cm_ahb_get_clock_divider() apply here as well. It may block. It cannot be called from Interrupt Context.

cm_cpu_clk_get_fromISR()

cpu_clk_t cm_cpu_clk_get_fromISR

(

void

)

Returns the CPU clock frequency (interrupt safe).

Returns

The CPU clock being used.

Warning

It can be called from Interrupt Context.

cm_enable_xtalm()

void cm_enable_xtalm

(

void

)

Start the fast XTAL clock (XTALxxM)

Checks if the fast XTAL clock (XTALxxM) is started. If not, it checks if there is a PDC entry for starting the fast XTAL clock (XTALxxM). If there is, it uses PDC to start the fast XTAL clock (XTALxxM). Otherwise, it enables the fast XTAL clock (XTALxxM) using hw_clk_enable_sysclk().

cm_halt_until_sysclk_ready()

__RETAINED_CODE void cm_halt_until_sysclk_ready

(

void

)

Halt until system clock (either PLL or XTAL32M) is ready.

It executes a WFI() call waiting for the XTALxxM Ready interrupt and PLL LOCK interrupt if needed.

cm_halt_until_xtalm_ready()

__RETAINED_CODE void cm_halt_until_xtalm_ready

(

void

)

Halt until the fast XTAL clock (XTALxxM) has settled.

It executes a WFI() call waiting for the fast XTAL clock (XTALxxM) Ready interrupt. Any other interrupts that hit are served.

cm_poll_xtalm_ready()

__RETAINED_CODE bool cm_poll_xtalm_ready

(

void

)

Check if the fast XTAL clock (XTALxxM) is ready.

Returns

True if the fast XTAL clock (XTALxxM) has settled, else false.

cm_register_xtal_ready_callback()

void cm_register_xtal_ready_callback

(

void(*)(void)

cb

)

Register a callback function to be called then XTAL32M is ready.

cb pointer to the callback function

cm_sys_clk_get()

sys_clk_t cm_sys_clk_get

(

void

)

Returns the sys_clk that the system uses at that moment.

Returns

The real sys_clk used by the system.

Warning

It may block. It cannot be called from Interrupt Context.

cm_sys_clk_get_fromISR()

sys_clk_t cm_sys_clk_get_fromISR

(

void

)

Returns the sys_clk that the system uses at that moment (interrupt safe version).

Returns

The real sys_clk used by the system.

cm_sys_clk_init()

void cm_sys_clk_init

(

sys_clk_t

type

)

Initialize clocks after power-up.

Parameters

[in]

type

The clock source to use as the system clock.

Warning

It must be called with interrupts enabled! It must be called only once, after power-up.

cm_sys_clk_release()

cm_sys_clk_status_t cm_sys_clk_release

(

sys_clk_t

type

)

Restores the system clock. It terminates a matching request.

If there are other sys_clk requests that are still active (i.e. not released), the system will switch to the one that has the highest priority. Otherwise, it will switch to the initial sys_clk that was specified when cm_sys_clk_init() was called. No change however will be made if Div1 is in use.

Parameters

[in]

type

The clock source the system was requested to use, when the matching cm_sys_clk_request() was called.

Returns

cm_sysclk_success if the release operation was completed successfully and either triggered a switch to a lower_priority sys_clk or did not trigger any sys_clk_change (either because there are still other active requests for the same sys_clk that have not been released yet or because there are no other active requests and the released sys_clk is also the default one (as specified in cm_sys_clk_init()))

cm_sysclk_div1_clk_in_use if the release operation was completed successfully and it should normally trigger a new sys_clk change (based on other active requests) but it didn't because a peripheral is clocked by the Div1 clock

Warning

This function must be called ONLY for terminating a matching cm_sys_clk_request. If called alone the system will reach an error-state!

It cannot be called from Interrupt Context.

It may block.

See also

cm_sys_clk_request

cm_sys_clk_request()

cm_sys_clk_status_t cm_sys_clk_request

(

sys_clk_t

type

)

Request for system clock switch.

This function can be used for system clock switching. It requests from the Clock Manager to use a specific clock source as system clock (sys_clk). If this is possible, the request is accepted and the function switches the sys_clk setting to the selected clock source and returns cm_sysclk_success. Otherwise, the request is rejected and the function returns a value that denotes the reason why the switch was not possible.

The request can be cancelled/released later by calling cm_sys_clk_release(). Until then, the requested sys_clk is protected from any lower priority sys_clk requests (with the priority as defined by cm_sys_clk_set_priority()).

There are two reasons that make the switching of the system clock not possible. Either there is at least one peripheral that currently uses the Div1 clock, or the current system clock has higher priority and is currently in use. In the second case, a successful switch requires a preceding release operation.

If the request involves enabling the fast Xtal clock (XTAL32M), then, apart from powering on the XTAL32M, the function will wait for it to settle before setting it as sys_clk. If the Doubler is requested, the function will also wait for the Doubler to be available.

The Clock Manager will also take care of automatically restoring the sys_clk to the requested setting after each wake-up.

Parameters

[in]

type

The clock source to use as sys_clk.

Returns

cm_sysclk_success if the requested sys_clk switch was applied

cm_sysclk_div1_clk_in_use if the sys_clk cannot be switched because a peripheral is clocked by the Div1 clock

cm_sysclk_higher_prio_used if a higher priority system clock is still in use

Note

Requires a preceding call of cm_sys_clk_set_priority().

Even if the request is rejected, it is still taken into account (until cancelled by a corresponding cm_sys_clk_release() call), and the switch to the requested clock may take place later (e.g. as soon as the existing higher priority clock requests are released).

Warning

It cannot be called from Interrupt Context.

It may block.

See also

cm_sys_clk_set_priority()

cm_sys_clk_release()

cm_sys_clk_set_priority()

void cm_sys_clk_set_priority

(

sys_clk_t *

sys_clk_prio_array

)

Set the system clock priority.

The system clock priority indicates which sys_clk prevails against another one when requesting a new sys_clk using cm_sys_clk_request().

Parameters

[in]

sys_clk_prio_array

pointer to array containing the system clock priority (in decreasing order)

Note

The provided array is expected to hold the first three members of the sys_clk_t enum in the order that denotes the desired priority scheme, with each type appearing only once in the array and the first element denoting the highest priority sys_clk. In case the array contains more elements, only the first three are taken into account.

The default clocks priority in decreasing order is the following: sysclk_DBLR64 sysclk_XTAL32M sysclk_RC32

The application can select a different clock priorities order by creating a local temporary priorities struct instance with the clocks in the desired priority order and then call the cm_sys_clk_set_priority() like in the example below. If the priorities are not set by the application before the first call of cm_sys_clk_request() or cm_sys_clk_release(), then the default priorities will be applied.

sys_clk_t sys_clk_p[] = {
                             sysclk_DBLR64,
                             sysclk_XTAL32M,
                             sysclk_RC32
                  };
 
                  cm_sys_clk_set_priority(sys_clk_p);

Warning

It has to be called only once, after power-up and before calling cm_sys_clk_init(). If not called the default clocks priority is used.

See also

cm_sys_clk_request()

cm_sys_clk_release()

cm_sys_clk_sleep()

__RETAINED_CODE void cm_sys_clk_sleep

(

bool

entering_sleep

)

Set the system clock (unprotected).

It attempts to:

• Prepare the system clock for sleep : called when the system is entering power-down mode. The system clock settings of the application are kept in order to be able to restore them. If the PLL is active it will be turned off. (It is called with the scheduler stopped and all interrupts disabled in this case.)
• Restore the previous setting : called when the fast XTAL clock (XTALxxM) settles. (It is called from ISR context with all interrupts disabled in this case.)

Parameters

[in]

entering_sleep

true if the system is going to sleep, else false.

Warning

It must be called from Interrupt Context and/or with all interrupts disabled. The function is internal to the clock and power managers and should not be used externally!

cm_wait_dblr_ready()

void cm_wait_dblr_ready

(

void

)

Block until the Doubler is ready.

Warning

It may block. It cannot be called from Interrupt Context.

cm_wait_xtalm_ready()

void cm_wait_xtalm_ready

(

void

)

Block until the fast XTAL clock (XTALxxM) is ready. If the fast XTAL clock (XTALxxM) is running then the function exits immediately.

Warning

It may block. It cannot be called from Interrupt Context.