Power profiles API set_pll

This routine sets up the system PLL according to the calling arguments. If the expected clock can be obtained by simply dividing the system PLL input, set_pll bypasses the PLL to lower system power consumption.

Note: Before this routine is invoked, the PLL clock source (IRC/system oscillator) must be selected (SYSCON registerName = SYSPLLCLKSEL addressOffset = 0x040), the main clock source must be set to the input clock to the system PLL (SYSCON registerName = MAINCLKSEL addressOffset = 0x070). and the system/AHB clock divider must be set to 1 (SYSCON registerName = SYSAHBCLKDIV addressOffset = 0x078).

set_pll attempts to find a PLL setup that matches the calling parameters. Once a combination of a feedback divider value (SYSPLLCTRL, M), a post divider ratio (SYSPLLCTRL, P) and the system/AHB clock divider (SYSAHBCLKDIV) is found, set_pll applies the selected values and switches the main clock source selection to the system PLL clock out (if necessary).

The routine returns a result code that indicates if the system PLL was successfully set (PLL_CMD_SUCCESS) or not (in which case the result code identifies what went wrong). The current system frequency value is also returned. The application should use this information to adjust other clocks in the device (the SSP, UART, and WDT clocks, and/or clockout).

Table 1. Power profiles API set_pll routine
Routine set_pll

Param0: system PLL input frequency (in kHz)

Param1: expected system clock (in kHz)


Param3: system PLL lock time-out



Result1: system clock (in kHz)

The following definitions are needed when making set_pll power routine calls:

/* set_pll mode options */-->
#define		CPU_FREQ_EQU				0-->
#define		CPU_FREQ_LTE				1-->
#define		CPU_FREQ_GTE				2-->
#define		CPU_FREQ_APPROX				3-->
/* set_pll result0 options */-->
#define		PLL_CMD_SUCCESS				0-->
#define		PLL_INVALID_FREQ				1-->
#define		PLL_INVALID_MODE				2-->
#define		PLL_FREQ_NOT_FOUND				3-->
#define		PLL_NOT_LOCKED				4-->

For a simplified clock configuration scheme see c-Generaldescription.html#BABJIGIB__CJADFGIG.

Power profiles API Param0: system PLL input frequency and Param1: expected system clock

set_pll configures a setup in which the main clock does not exceed 30 MHz (see c-Generaldescription.html#BABJIGIB__CJADFGIG). It easily finds a solution when the ratio between the expected system clock and the system PLL input frequency is an integer value, but it can also find solutions in other cases.

The system PLL input frequency (Param0) must be between 10 000 to 25 000 kHz (10 MHz to 25 MHz) inclusive. The expected system clock (Param1) must be between 1 and 30 000 kHz inclusive. If either of these requirements is not met, set_pll returns PLL_INVALID_FREQ and returns Param0 as Result1 since the PLL setting is unchanged.

Power profiles API Param2: mode

The first priority of set_pll is to find a setup that generates the system clock at exactly the rate specified in Param1. If it is unlikely that an exact match can be found, input parameter mode (Param2) should be used to specify if the actual system clock can be less than or equal, greater than or equal or approximately the value specified as the expected system clock (Param1).

A call specifying CPU_FREQ_EQU will only succeed if the PLL can output exactly the frequency requested in Param1.

CPU_FREQ_LTE can be used if the requested frequency should not be exceeded (such as overall current consumption and/or power budget reasons).

CPU_FREQ_GTE helps applications that need a minimum level of CPU processing capabilities.

CPU_FREQ_APPROX results in a system clock that is as close as possible to the requested value (it may be greater than or less than the requested value).

If an illegal mode is specified, set_pll returns PLL_INVALID_MODE. If the expected system clock is out of the range supported by this routine, set_pll returns PLL_FREQ_NOT_FOUND. In these cases the current PLL setting is not changed and Param0 is returned as Result1.

Power profiles API Param3: system PLL lock time-out

It should take no more than 100 μs for the system PLL to lock if a valid configuration is selected. If Param3 is zero, set_pll will wait indefinitely for the PLL to lock. A non-zero value indicates how many times the code will check for a successful PLL lock event before it returns PLL_NOT_LOCKED. In this case the PLL settings are unchanged and Param0 is returned as Result1.

Note: The time it takes the PLL to lock depends on the selected PLL input clock source (IRC/system oscillator) and its characteristics. The selected source can experience more or less jitter depending on the operating conditions such as power supply and/or ambient temperature. This is why it is suggested that when a good known clock source is used and a PLL_NOT_LOCKED response is received, the set_pll routine should be invoked several times before declaring the selected PLL clock source invalid.

Hint: setting Param3 equal to the system PLL frequency [Hz] divided by 10 000 will provide more than enough PLL lock-polling cycles.