NHS31xx SW API
clock: Clock driver

Detailed Description

The Clock driver provides the API to control functionalities related with the handling of clocks. This functionality is part of the SYSCON HW block, however, for clarity it is exposed in an API separate from the SYSCON driver.

Note
All the registers that belong to the SYSCON HW block (including the ones related with handling of clocks) are defined in the SYSCON driver.

The chip provides two internal clock sources:

The Clock driver allows configuring the separate clocks that drive all the mentioned domains, namely regarding division, gating and selection of the clock sources.

Clock Division:
The chip provides three separate clock dividers, all acting on the SFRO clock, that output three separate clocks:
  1. System Clock divider: Divides the SFRO into the clock that drives the System Clock (AHB Clock) and the Peripheral Clocks. This divider is configured to 16 by default (500 kHz) and can be configured using the Chip_Clock_System_SetClockFreq function.
  2. SPI Clock divider: Divides the SFRO into the clock that drives the SPI HW block. This divider is configured to 0 by default (disabled) and can be configured using the Chip_Clock_SPI0_SetClockFreq function.
  3. Watchdog Clock divider: Divides the selected Watchdog clock source (SFRO by default) into the clock that drives the Watchdog timer. This divider is configured to 0 by default (disabled) and can be configured using the Chip_Clock_Watchdog_SetClockFreq function.
Clock Gating:
The clocks to peripheral HW blocks can be enabled and disabled using the Chip_Clock_Peripheral_EnableClock and Chip_Clock_Peripheral_DisableClock functions. The HW blocks whose clock can be disabled/enabled are defined in CLOCK_PERIPHERAL_T enum. All peripheral clocks are disabled by default except for the RAM memory, Flash controller, Flash memory, IOCON block, EEPROM controller and EEPROM memory.
Clock Selection:
The chip allows selecting the clock source for two separate clocks: Note that the TFRO is part of the Power Management Unit (PMU) HW block, which is an always-on power domain. The handling of this clock source is, thus, covered in the PMU driver.

Enumerations

enum  CLOCK_PERIPHERAL_T {
  CLOCK_PERIPHERAL_RAM = (1 << 2),
  CLOCK_PERIPHERAL_FLASH = (3 << 3),
  CLOCK_PERIPHERAL_I2C0 = (1 << 5),
  CLOCK_PERIPHERAL_GPIO = (1 << 6),
  CLOCK_PERIPHERAL_SPI0 = (1 << 7),
  CLOCK_PERIPHERAL_16TIMER0 = (1 << 8),
  CLOCK_PERIPHERAL_32TIMER0 = (1 << 9),
  CLOCK_PERIPHERAL_RTC = (1 << 10),
  CLOCK_PERIPHERAL_WATCHDOG = (1 << 11),
  CLOCK_PERIPHERAL_TSEN = (1 << 12),
  CLOCK_PERIPHERAL_C2D = (1 << 13),
  CLOCK_PERIPHERAL_I2D = (1 << 15),
  CLOCK_PERIPHERAL_ADCDAC = (1 << 16),
  CLOCK_PERIPHERAL_IOCON = (1 << 18),
  CLOCK_PERIPHERAL_EEPROM = (3 << 19)
}
 
enum  CLOCK_WATCHDOGSOURCE_T {
  CLOCK_WATCHDOGSOURCE_SFRO = 0,
  CLOCK_WATCHDOGSOURCE_VSS = 2
}
 
enum  CLOCK_CLKOUTSOURCE_T {
  CLOCK_CLKOUTSOURCE_DISABLED = 0,
  CLOCK_CLKOUTSOURCE_SFRO = 1,
  CLOCK_CLKOUTSOURCE_SYSTEM = 3,
  CLOCK_CLKOUTSOURCE_TFRO = 5,
  CLOCK_CLKOUTSOURCE_NFC = 7
}
 

Functions

void Chip_Clock_System_SetClockDiv (int divisor)
 
int Chip_Clock_System_GetClockDiv (void)
 
void Chip_Clock_System_SetClockFreq (int frequency)
 
int Chip_Clock_System_GetClockFreq (void)
 
void Chip_Clock_System_BusyWait_us (uint32_t us)
 
void Chip_Clock_System_BusyWait_ms (int ms)
 
void Chip_Clock_SPI0_SetClockDiv (int divisor)
 
int Chip_Clock_SPI0_GetClockDiv (void)
 
void Chip_Clock_SPI0_SetClockFreq (int frequency)
 
int Chip_Clock_SPI0_GetClockFreq (void)
 
void Chip_Clock_Watchdog_SetClockDiv (int divisor)
 
int Chip_Clock_Watchdog_GetClockDiv (void)
 
void Chip_Clock_Watchdog_SetClockFreq (int frequency)
 
int Chip_Clock_Watchdog_GetClockFreq (void)
 
void Chip_Clock_Peripheral_EnableClock (CLOCK_PERIPHERAL_T bitvector)
 
void Chip_Clock_Peripheral_DisableClock (CLOCK_PERIPHERAL_T bitvector)
 
void Chip_Clock_Peripheral_SetClockEnabled (CLOCK_PERIPHERAL_T bitvector)
 
CLOCK_PERIPHERAL_T Chip_Clock_Peripheral_GetClockEnabled (void)
 
void Chip_Clock_Watchdog_SetClockSource (CLOCK_WATCHDOGSOURCE_T source)
 
CLOCK_WATCHDOGSOURCE_T Chip_Clock_Watchdog_GetClockSource (void)
 
void Chip_Clock_Clkout_SetClockSource (CLOCK_CLKOUTSOURCE_T source)
 
CLOCK_CLKOUTSOURCE_T Chip_Clock_Clkout_GetClockSource (void)
 

Enumeration Type Documentation

◆ CLOCK_PERIPHERAL_T

Possible Peripheral clocks that can be enabled/disabled

Enumerator
CLOCK_PERIPHERAL_RAM 

Represents the RAM memory clock

CLOCK_PERIPHERAL_FLASH 

Represents the Flash memory clock

CLOCK_PERIPHERAL_I2C0 

Represents the I2C0 clock

CLOCK_PERIPHERAL_GPIO 

Represents the GPIO clock

CLOCK_PERIPHERAL_SPI0 

Represents the SPI0 register access clock (The SPI0 block itself is clocked by a separate clock)

CLOCK_PERIPHERAL_16TIMER0 

Represents the 16 bit timer 0 clock

CLOCK_PERIPHERAL_32TIMER0 

Represents the 32 bit timer 0 clock

CLOCK_PERIPHERAL_RTC 

Represents the RTC clock register access clock only (The RTC block itself is clocked by a separate clock source)

CLOCK_PERIPHERAL_WATCHDOG 

Represents the Watchdog register access clock only (The Watchdog block itself is clocked by a separate clock)

CLOCK_PERIPHERAL_TSEN 

Represents the Temperature Sensor clock

CLOCK_PERIPHERAL_C2D 

Represents the Capacitance to Digital converter clock

CLOCK_PERIPHERAL_I2D 

Represents the Current to Digital converter clock

CLOCK_PERIPHERAL_ADCDAC 

Represents the Analog-to-Digital/Digital-to-Analog converter clock

CLOCK_PERIPHERAL_IOCON 

Represents the I/O configuration block clock

CLOCK_PERIPHERAL_EEPROM 

Represents the EEPROM memory clock

◆ CLOCK_WATCHDOGSOURCE_T

Possible clock sources for the Watchdog

Enumerator
CLOCK_WATCHDOGSOURCE_SFRO 

SFRO (8MHz) as the Watchdog clock source

CLOCK_WATCHDOGSOURCE_VSS 

VSS as the Watchdog clock source (no Clock)

◆ CLOCK_CLKOUTSOURCE_T

Possible clock sources for the CLKOUT pin

Enumerator
CLOCK_CLKOUTSOURCE_DISABLED 

Disables the CLKOUT pin output

CLOCK_CLKOUTSOURCE_SFRO 

SFRO (8MHz) as the CLKOUT pin clock source

CLOCK_CLKOUTSOURCE_SYSTEM 

System Clock (62.5 kHz - 8MHz) as the CLKOUT pin clock source

CLOCK_CLKOUTSOURCE_TFRO 

TFRO (32.768 kHz) as the CLKOUT pin clock source

CLOCK_CLKOUTSOURCE_NFC 

NFC clock (1.695 MHz) as the CLKOUT pin clock source

Function Documentation

◆ Chip_Clock_System_SetClockDiv()

void Chip_Clock_System_SetClockDiv ( int  divisor)

Sets the division factor that divides the SFRO for the clock that drives the System Clock and the Peripheral Clocks. The maximum division factor is 128 and only powers of 2 are valid (e.g. 1,2,4,8,..,128). 0 is NOT allowed.

Parameters
divisor: The division factor to set
Precondition
The precondition listed in Chip_Clock_System_SetClockFreq applies here as well.
Note
This setting affects the core execution speed. This is a low level function, use Chip_Clock_System_SetClockFreq instead.
If not valid, the 'divisor' will be clipped to the largest power of 2 lower than or equal to it, however up-clipped to 128. Use the Chip_Clock_System_GetClockDiv to retrieve the actual divisor that was set.

◆ Chip_Clock_System_GetClockDiv()

int Chip_Clock_System_GetClockDiv ( void  )

Gets the division factor that divides the SFRO for the clock that drives the System Clock and the Peripheral Clocks.

Returns
The division factor. The maximum division factor is 128 and only powers of 2 are valid (e.g. 1,2,4,8,..,128)
Note
The default value for the division factor is 16 (500kHz).

◆ Chip_Clock_System_SetClockFreq()

void Chip_Clock_System_SetClockFreq ( int  frequency)

Sets the System Clock frequency in Hz.

Parameters
frequency: The System Clock frequency in Hz to set
Note
This setting affects the core execution speed.
Only a set of frequencies is supported. If not valid, the 'frequency' will be clipped to the closest supported value higher than or equal to it. The System Clock frequency range is (62.5 kHz - 8MHz). Frequencies of 0 and higher than 8MHz are NOT allowed. Use the Chip_Clock_System_GetClockFreq to retrieve the actual frequency that was set.
Precondition
If frequency equals 4000001 or higher, system clock divisor will become 1. The caller must ensure that either Failure to do so will result in a hard fault (flash access error). See also SW Clock Restrictions

◆ Chip_Clock_System_GetClockFreq()

int Chip_Clock_System_GetClockFreq ( void  )

Gets the System Clock frequency in Hz

Returns
The System Clock frequency in Hz
Note
The default value for the System Clock frequency is 500 kHz

◆ Chip_Clock_System_BusyWait_us()

void Chip_Clock_System_BusyWait_us ( uint32_t  us)

Waits the specified amount of time (using instruction counting)

Parameters
us: number of microseconds to wait
Note
This function does not wait if us <= 0.
The wait time shall not exceed 4 000 000 us.
The wait time is guaranteed to be at least us, but it will be somewhat longer.
Due to the function overhead, for the error to be under 10% us should be at least the equivalent of 512 system ticks. i.e.: us > 512 / system clock frequency (in MHz)

◆ Chip_Clock_System_BusyWait_ms()

void Chip_Clock_System_BusyWait_ms ( int  ms)

Waits the specified amount of time (using instruction counting)

Parameters
ms: number of milliseconds to wait
Note
This function does not wait if ms <= 0.
The wait time is guaranteed to be at least ms, but it will be somewhat longer.
This function is just a wrapper for Chip_Clock_System_BusyWait_us.

◆ Chip_Clock_SPI0_SetClockDiv()

void Chip_Clock_SPI0_SetClockDiv ( int  divisor)

Sets the division factor that divides the SFRO into the clock that drives the SPI0 HW block. The supported division factors are 1 and 2-254 (even numbers) and 0 can be used to disable the clock.

Parameters
divisor: The division factor to set
Note
This is a low level function, use Chip_Clock_SPI0_SetClockFreq instead.
If not valid, the divisor will be clipped to 254. Odd divisors are floored to nearest even number, except when divisor is 1.

◆ Chip_Clock_SPI0_GetClockDiv()

int Chip_Clock_SPI0_GetClockDiv ( void  )

Gets the division factor that divides the SFRO into the clock that drives the SPI0 HW block.

Returns
The division factor. The supported division factors are 1 and 2-254 (even numbers) and 0 means that the clock is disabled.
Note
The default value for the division factor is 0 (disabled).

◆ Chip_Clock_SPI0_SetClockFreq()

void Chip_Clock_SPI0_SetClockFreq ( int  frequency)

Sets the frequency in Hz of the clock that drives the SPI0 HW block.

Parameters
frequency: The clock frequency in Hz to set
Note
Only a set of frequencies is supported. If not valid, the 'frequency' will be clipped to the closest supported value higher than or equal to it. The SPI0 clock frequency range is (~31.373 kHz - 8MHz). Use the Chip_Clock_SPI0_GetClockFreq to retrieve the actual frequency that was set. Setting a frequency value of 0 Hz or higher than 8MHz disables the clock.

◆ Chip_Clock_SPI0_GetClockFreq()

int Chip_Clock_SPI0_GetClockFreq ( void  )

Gets the frequency in Hz of the clock that drives the SPI0 HW block.

Returns
The clock frequency in Hz
Note
If the clock is disabled, 0 is returned. The clock is disabled by default.
The returned frequency value is rounded to the closest integer.

◆ Chip_Clock_Watchdog_SetClockDiv()

void Chip_Clock_Watchdog_SetClockDiv ( int  divisor)

Sets the division factor that divides the SFRO into the clock that drives the Watchdog. The supported division factors are 1 and 2-254 (even numbers) and 0 can be used to disable the clock.

Parameters
divisor: The division factor to set
Note
If not valid, the divisor will be clipped to 254. Odd divisors are floored to nearest even number, except when divisor is 1.

◆ Chip_Clock_Watchdog_GetClockDiv()

int Chip_Clock_Watchdog_GetClockDiv ( void  )

Gets the division factor that divides the SFRO into the clock that drives the Watchdog.

Returns
The division factor. The supported division factors are 1 and 2-254 (even numbers) and 0 means that the clock is disabled.
Note
The default value for the division factor is 0 (disabled).

◆ Chip_Clock_Watchdog_SetClockFreq()

void Chip_Clock_Watchdog_SetClockFreq ( int  frequency)

Sets the frequency in Hz of the clock that drives the Watchdog.

Parameters
frequency: The clock frequency in Hz to set
Note
Only a set of frequencies is supported. If not valid, the 'frequency' will be clipped to the closest supported value higher than or equal to it. The Watchdog clock frequency range is (~31.373 kHz - 8MHz). Use the Chip_Clock_Watchdog_GetClockFreq to retrieve the actual frequency that was set. Setting a frequency value of 0 Hz disables the clock.

◆ Chip_Clock_Watchdog_GetClockFreq()

int Chip_Clock_Watchdog_GetClockFreq ( void  )

Gets the clock frequency in Hz of the clock that drives the Watchdog.

Returns
The clock frequency in Hz
Note
If the clock is disabled, 0 is returned. The clock is disabled by default.
The returned frequency value is rounded to the closest integer.

◆ Chip_Clock_Peripheral_EnableClock()

void Chip_Clock_Peripheral_EnableClock ( CLOCK_PERIPHERAL_T  bitvector)

Enables peripheral clock(s).

Parameters
bitvector: Bitvector of the peripheral(s) whose clock to enable
Note
All peripheral clocks are disabled by default except CLOCK_PERIPHERAL_RAM, CLOCK_PERIPHERAL_FLASH, CLOCK_PERIPHERAL_IOCON, CLOCK_PERIPHERAL_EEPROM.
Only the peripheral clock(s) set in bitvector are changed. All the others are left untouched.
This functionality is overlapped with the Chip_Clock_Peripheral_SetClockEnabled function
Warning
Directly accessing Flash or EEPROM controller addresses (NSS_FLASH_T, NSS_EEPROM_T) when the respective clock is disabled, blocks the APB bus indefinitely.

◆ Chip_Clock_Peripheral_DisableClock()

void Chip_Clock_Peripheral_DisableClock ( CLOCK_PERIPHERAL_T  bitvector)

Disables peripheral clock(s).

Parameters
bitvector: Bitvector of the peripheral(s) whose clock to disable
Note
All peripheral clocks are disabled by default except CLOCK_PERIPHERAL_RAM, CLOCK_PERIPHERAL_FLASH, CLOCK_PERIPHERAL_IOCON, CLOCK_PERIPHERAL_EEPROM.
Only the peripheral clock(s) set in bitvector are changed. All the others are left untouched.
This functionality is overlapped with the Chip_Clock_Peripheral_SetClockEnabled function
Warning
Directly accessing Flash or EEPROM controller addresses (NSS_FLASH_T, NSS_EEPROM_T) when the respective clock is disabled, blocks the APB bus indefinitely.

◆ Chip_Clock_Peripheral_SetClockEnabled()

void Chip_Clock_Peripheral_SetClockEnabled ( CLOCK_PERIPHERAL_T  bitvector)

Enables/Disables the clock of the peripheral(s) described in CLOCK_PERIPHERAL_T

Parameters
bitvector: Bitvector of the peripheral(s) whose clock to enable/disable
Note
This setting overwrites the existing setting for all the peripherals described in CLOCK_PERIPHERAL_T.
If the respective bit is set, the clock of the respective peripheral will be enabled, otherwise it will be disabled.
This functionality is overlapped with the Chip_Clock_Peripheral_EnableClock and Chip_Clock_Peripheral_DisableClock functions
Warning
Directly accessing Flash or EEPROM controller addresses (NSS_FLASH_T, NSS_EEPROM_T) when the respective clock is disabled, blocks the APB bus indefinitely.

◆ Chip_Clock_Peripheral_GetClockEnabled()

CLOCK_PERIPHERAL_T Chip_Clock_Peripheral_GetClockEnabled ( void  )

Retrieves a bitvector stating the enabled/disabled peripheral clock(s) described in CLOCK_PERIPHERAL_T

Returns
Bitvector stating the enabled/disabled peripheral clock(s)
Note
If the respective bit is set, the clock of the respective peripheral is enabled, otherwise it is disabled.
All peripheral clocks are disabled by default except CLOCK_PERIPHERAL_RAM, CLOCK_PERIPHERAL_FLASH, CLOCK_PERIPHERAL_IOCON, CLOCK_PERIPHERAL_EEPROM.

◆ Chip_Clock_Watchdog_SetClockSource()

void Chip_Clock_Watchdog_SetClockSource ( CLOCK_WATCHDOGSOURCE_T  source)

Sets the Watchdog clock source.

Parameters
source: The Watchdog clock source to set

◆ Chip_Clock_Watchdog_GetClockSource()

CLOCK_WATCHDOGSOURCE_T Chip_Clock_Watchdog_GetClockSource ( void  )

Gets the Watchdog clock source.

Returns
The Watchdog clock source
Note
The default Watchdog clock source is CLOCK_WATCHDOGSOURCE_SFRO.

◆ Chip_Clock_Clkout_SetClockSource()

void Chip_Clock_Clkout_SetClockSource ( CLOCK_CLKOUTSOURCE_T  source)

Sets the CLKOUT pin clock source.

Parameters
source: The CLKOUT pin clock source to set

◆ Chip_Clock_Clkout_GetClockSource()

CLOCK_CLKOUTSOURCE_T Chip_Clock_Clkout_GetClockSource ( void  )

Gets the CLKOUT pin clock source.

Returns
The CLKOUT pin clock source
Note
The default CLKOUT pin clock source is CLOCK_CLKOUTSOURCE_DISABLED.