Overview

The MCUxpreeso SDK provides a driver for the 32kHz Clock Control Module (CCM32K)

Control 32kHz free-running oscillator

The function CCM32K_Enable32kFro() can be used to enable/disable 32kHz free-running oscillator. To trim the frequency of output clock when the clock source is selected as 32kHz free-running oscillator, the function CCM32K_Get32kFroTrimValue() has been provided to realize this feature.

Control 32kHz crystal oscillator

The function CCM32K_Set32kOscConfig() can be used to enable/disable/bypass 32kHz Crystal Oscillator. If the parameter "mode" is selected as kCCM32K_Disable32kHzCrystalOsc it means to disable the 32kHz Crystal Oscillator. If the parameter "mode" is selected as kCCM32K_Bypass32kHzCrystalOsc, it means the application uses the 32kHz Oscillator or 32kHz external clock from EXTAL pin.

Data Structures
struct	ccm32k_clock_monitor_config_t
	Clock monitor configuration structure. More...

struct	ccm32k_osc_config_t
	The structure of oscillator configuration. More...

Enumerations
enum	ccm32k_osc_xtal_cap_t { kCCM32K_OscXtal0pFCap = 0x0U, kCCM32K_OscXtal2pFCap = 0x1U, kCCM32K_OscXtal4pFCap = 0x2U, kCCM32K_OscXtal6pFCap = 0x3U, kCCM32K_OscXtal8pFCap = 0x4U, kCCM32K_OscXtal10pFCap = 0x5U, kCCM32K_OscXtal12pFCap = 0x6U, kCCM32K_OscXtal14pFCap = 0x7U, kCCM32K_OscXtal16pFCap = 0x8U, kCCM32K_OscXtal18pFCap = 0x9U, kCCM32K_OscXtal20pFCap = 0xAU, kCCM32K_OscXtal22pFCap = 0xBU, kCCM32K_OscXtal24pFCap = 0xCU, kCCM32K_OscXtal26pFCap = 0xDU, kCCM32K_OscXtal28pFCap = 0xEU, kCCM32K_OscXtal30pFCap = 0xFU }
	The enumerator of internal capacitance of OSC's XTAL pin. More...

enum	ccm32k_osc_extal_cap_t { kCCM32K_OscExtal0pFCap = 0x0U, kCCM32K_OscExtal2pFCap = 0x1U, kCCM32K_OscExtal4pFCap = 0x2U, kCCM32K_OscExtal6pFCap = 0x3U, kCCM32K_OscExtal8pFCap = 0x4U, kCCM32K_OscExtal10pFCap = 0x5U, kCCM32K_OscExtal12pFCap = 0x6U, kCCM32K_OscExtal14pFCap = 0x7U, kCCM32K_OscExtal16pFCap = 0x8U, kCCM32K_OscExtal18pFCap = 0x9U, kCCM32K_OscExtal20pFCap = 0xAU, kCCM32K_OscExtal22pFCap = 0xBU, kCCM32K_OscExtal24pFCap = 0xCU, kCCM32K_OscExtal26pFCap = 0xDU, kCCM32K_OscExtal28pFCap = 0xEU, kCCM32K_OscExtal30pFCap = 0xFU }
	The enumerator of internal capacitance of OSC's EXTAL pin. More...

enum	ccm32k_osc_coarse_adjustment_value_t
	The enumerator of osc amplifier coarse fine adjustment. More...

enum	ccm32k_osc_mode_t { kCCM32K_Disable32kHzCrystalOsc = 0x0U, kCCM32K_Enable32kHzCrystalOsc = 0x1U, kCCM32K_Bypass32kHzCrystalOsc = 0x3U }
	The enumerator of 32kHz oscillator. More...

enum	{ kCCM32K_32kOscReadyStatusFlag = CCM32K_STATUS_OSC32K_RDY_MASK, kCCM32K_32kOscActiveStatusFlag = CCM32K_STATUS_OSC32K_ACTIVE_MASK, kCCM32K_32kFroActiveStatusFlag = CCM32K_STATUS_FRO32K_ACTIVE_MASK, kCCM32K_ClockDetectStatusFlag = CCM32K_STATUS_CLOCK_DET_MASK }
	The enumerator of CCM32K status flag. More...

enum	ccm32k_state_t { kCCM32K_Both32kFro32kOscDisabled, kCCM32K_Only32kFroEnabled = 0x1U, kCCM32K_Only32kOscEnabled = 0x2U, kCCM32K_Both32kFro32kOscEnabled = ((uint8_t)kCCM32K_Only32kFroEnabled \| (uint8_t)kCCM32K_Only32kOscEnabled) }
	The enumerator of module state. More...

enum	ccm32k_clock_source_t { kCCM32K_ClockSourceNone = 0x0U, kCCM32K_ClockSource32kFro = 0x1U, kCCM32K_ClockSource32kOsc = 0x2U }
	The enumerator of clock source. More...

enum	ccm32k_clock_monitor_freq_trim_value_t { kCCM32K_ClockMonitor2CycleAssert = 0x0U, kCCM32K_ClockMonitor4CycleAssert, kCCM32K_ClockMonitor6CycleAssert, kCCM32K_ClockMonitor8CycleAssert }
	Clock monitor frequency trim values. More...

enum	ccm32k_clock_monitor_divide_trim_value_t { kCCM32K_ClockMonitor_1kHzFro32k_1kHzOsc32k = 0x0U, kCCM32K_ClockMonitor_64HzFro32k_1kHzOsc32k = 0x1U, kCCM32K_ClockMonitor_1KHzFro32k_64HzOsc32k = 0x2U, kCCM32K_ClockMonitor_64HzFro32k_64HzOsc32k = 0x3U }
	Clock monitor divide trim values. More...

enum	ccm32k_clock_source_select_t { kCCM32K_ClockSourceSelectFro32k = 0x0U, kCCM32K_ClockSourceSelectOsc32k }
	CCM32K clock source enumeration. More...

enum	ccm32k_clock_output_peripheral_t { kCCM32K_ClockOutToRtc = 1U << 0U, kCCM32K_ClockOutToRfmc = 1U << 1U, kCCM32K_ClockOutToNbu = 1U << 2U, kCCM32K_ClockOutToWuuRmcPortD = 1U << 3U, kCCM32K_ClockOutToOtherModules = 1U << 4U }
	32kHz clock output peripheral bit map. More...

Driver version
#define	FSL_CCM32K_DRIVER_VERSION (MAKE_VERSION(2, 1, 1))
	CCM32K driver version 2.1.1. More...

32kHz Free-running Oscillator Interfaces
static void	CCM32K_Enable32kFro (CCM32K_Type *base, bool enable)
	Enable/Disable 32kHz free-running oscillator. More...

static void	CCM32K_Lock32kFroWriteAccess (CCM32K_Type *base)
	Lock all further write accesses to the FRO32K_CTRL register until a POR occurs. More...

static uint16_t	CCM32K_Get32kFroTrimValue (CCM32K_Type *base)
	Get frequency trim value of 32kHz free-running oscillator. More...

void	CCM32K_Set32kFroTrimValue (CCM32K_Type *base, uint16_t trimValue)
	Set the frequency trim value of 32kHz free-running oscillator by software. More...

static void	CCM32K_Disable32kFroIFRLoad (CCM32K_Type *base, bool disable)
	Disable/Enable the function of setting 32kHz free-running oscillator trim value when IFR value gets loaded in the SOC. More...

static void	CCM32K_Lock32kFroTrimWriteAccess (CCM32K_Type *base)
	Lock all further write accesses to the FRO32K_TRIM register until a POR occurs. More...

32kHz Crystal Oscillator Interfaces
void	CCM32K_Set32kOscConfig (CCM32K_Type base, ccm32k_osc_mode_t mode, const ccm32k_osc_config_t config)
	Config 32k Crystal Oscillator. More...

static void	CCM32K_Lock32kOscWriteAccess (CCM32K_Type *base)
	Lock all further write accesses to the OSC32K_CTRL register until a POR occurs. More...

Clock Monitor Control Interfaces
static void	CCM32K_EnableClockMonitor (CCM32K_Type *base, bool enable)
	Enable/disable clock monitor. More...

static void	CCM32K_SetClockMonitorFreqTrimValue (CCM32K_Type *base, ccm32k_clock_monitor_freq_trim_value_t trimValue)
	Set clock monitor frequency trim value. More...

static void	CCM32K_SetClockMonitorDivideTrimValue (CCM32K_Type *base, ccm32k_clock_monitor_divide_trim_value_t trimValue)
	Set clock monitor divide trim value. More...

void	CCM32K_SetClockMonitorConfig (CCM32K_Type base, const ccm32k_clock_monitor_config_t config)
	Config clock monitor one time, including frequency trim value, divide trim value. More...

static void	CCM32K_LockClockMonitorWriteAccess (CCM32K_Type *base)
	Lock all further write accesses to the CLKMON_CTRL register until a POR occurs. More...

Clock Gate Control Interfaces
static void	CCM32K_EnableCLKOutToPeripherals (CCM32K_Type *base, uint8_t peripheralMask)
	Enable 32kHz clock output to selected peripherals. More...

static void	CCM32K_DisableCLKOutToPeripherals (CCM32K_Type *base, uint8_t peripheralMask)
	Disable 32kHz clock output to selected peripherals. More...

static void	CCM32K_SelectClockSource (CCM32K_Type *base, ccm32k_clock_source_select_t clockSource)
	Select CCM32K module's clock source which will be provide to the device. More...

static void	CCM32K_LockClockGateWriteAccess (CCM32K_Type *base)
	Lock all further write access to the CGC32K register until a POR occurs. More...

Status Interface
static uint32_t	CCM32K_GetStatusFlag (CCM32K_Type *base)
	Get the status flag. More...

State/Clock Source Interfaces
ccm32k_state_t	CCM32K_GetCurrentState (CCM32K_Type *base)
	Get current state. More...

ccm32k_clock_source_t	CCM32K_GetClockSource (CCM32K_Type *base)
	Return current clock source. More...

Data Structure Documentation

struct ccm32k_clock_monitor_config_t

Data Fields
bool	enableClockMonitor
	Used to enable/disable clock monitor. More...

ccm32k_clock_monitor_freq_trim_value_t	freqTrimValue
	Clock minitor frequency trim value. More...

ccm32k_clock_monitor_divide_trim_value_t	divideTrimValue
	Clock minitor divide trim value. More...

Field Documentation

bool ccm32k_clock_monitor_config_t::enableClockMonitor

ccm32k_clock_monitor_freq_trim_value_t ccm32k_clock_monitor_config_t::freqTrimValue

ccm32k_clock_monitor_divide_trim_value_t ccm32k_clock_monitor_config_t::divideTrimValue

struct ccm32k_osc_config_t

Data Fields
bool	enableInternalCapBank
	enable/disable the internal capacitance bank. More...

ccm32k_osc_xtal_cap_t	xtalCap
	The internal capacitance for the OSC XTAL pin from the capacitor bank, only useful when the internal capacitance bank is enabled. More...

ccm32k_osc_extal_cap_t	extalCap
	The internal capacitance for the OSC EXTAL pin from the capacitor bank, only useful when the internal capacitance bank is enabled. More...

ccm32k_osc_coarse_adjustment_value_t	coarseAdjustment
	32kHz crystal oscillator amplifier coarse adjustment value. More...

Field Documentation

bool ccm32k_osc_config_t::enableInternalCapBank

ccm32k_osc_xtal_cap_t ccm32k_osc_config_t::xtalCap

ccm32k_osc_extal_cap_t ccm32k_osc_config_t::extalCap

ccm32k_osc_coarse_adjustment_value_t ccm32k_osc_config_t::coarseAdjustment

Macro Definition Documentation

#define FSL_CCM32K_DRIVER_VERSION (MAKE_VERSION(2, 1, 1))

Enumeration Type Documentation

enum ccm32k_osc_xtal_cap_t

Enumerator
kCCM32K_OscXtal0pFCap	The internal capacitance for XTAL pin is 0pF.
kCCM32K_OscXtal2pFCap	The internal capacitance for XTAL pin is 2pF.
kCCM32K_OscXtal4pFCap	The internal capacitance for XTAL pin is 4pF.
kCCM32K_OscXtal6pFCap	The internal capacitance for XTAL pin is 6pF.
kCCM32K_OscXtal8pFCap	The internal capacitance for XTAL pin is 8pF.
kCCM32K_OscXtal10pFCap	The internal capacitance for XTAL pin is 10pF.
kCCM32K_OscXtal12pFCap	The internal capacitance for XTAL pin is 12pF.
kCCM32K_OscXtal14pFCap	The internal capacitance for XTAL pin is 14pF.
kCCM32K_OscXtal16pFCap	The internal capacitance for XTAL pin is 16pF.
kCCM32K_OscXtal18pFCap	The internal capacitance for XTAL pin is 18pF.
kCCM32K_OscXtal20pFCap	The internal capacitance for XTAL pin is 20pF.
kCCM32K_OscXtal22pFCap	The internal capacitance for XTAL pin is 22pF.
kCCM32K_OscXtal24pFCap	The internal capacitance for XTAL pin is 24pF.
kCCM32K_OscXtal26pFCap	The internal capacitance for XTAL pin is 26pF.
kCCM32K_OscXtal28pFCap	The internal capacitance for XTAL pin is 28pF.
kCCM32K_OscXtal30pFCap	The internal capacitance for XTAL pin is 30pF.

enum ccm32k_osc_extal_cap_t

Enumerator
kCCM32K_OscExtal0pFCap	The internal capacitance for EXTAL pin is 0pF.
kCCM32K_OscExtal2pFCap	The internal capacitance for EXTAL pin is 2pF.
kCCM32K_OscExtal4pFCap	The internal capacitance for EXTAL pin is 4pF.
kCCM32K_OscExtal6pFCap	The internal capacitance for EXTAL pin is 6pF.
kCCM32K_OscExtal8pFCap	The internal capacitance for EXTAL pin is 8pF.
kCCM32K_OscExtal10pFCap	The internal capacitance for EXTAL pin is 10pF.
kCCM32K_OscExtal12pFCap	The internal capacitance for EXTAL pin is 12pF.
kCCM32K_OscExtal14pFCap	The internal capacitance for EXTAL pin is 14pF.
kCCM32K_OscExtal16pFCap	The internal capacitance for EXTAL pin is 16pF.
kCCM32K_OscExtal18pFCap	The internal capacitance for EXTAL pin is 18pF.
kCCM32K_OscExtal20pFCap	The internal capacitance for EXTAL pin is 20pF.
kCCM32K_OscExtal22pFCap	The internal capacitance for EXTAL pin is 22pF.
kCCM32K_OscExtal24pFCap	The internal capacitance for EXTAL pin is 24pF.
kCCM32K_OscExtal26pFCap	The internal capacitance for EXTAL pin is 26pF.
kCCM32K_OscExtal28pFCap	The internal capacitance for EXTAL pin is 28pF.
kCCM32K_OscExtal30pFCap	The internal capacitance for EXTAL pin is 30pF.

enum ccm32k_osc_coarse_adjustment_value_t

Tunes the internal transconductance (gm) by increasing the current.

enum ccm32k_osc_mode_t

Enumerator
kCCM32K_Disable32kHzCrystalOsc	Disable 32kHz Crystal Oscillator.
kCCM32K_Enable32kHzCrystalOsc	Enable 32kHz Crystal Oscillator.
kCCM32K_Bypass32kHzCrystalOsc	Bypass 32kHz Crystal Oscillator, use the 32kHz Oscillator or external 32kHz clock.

anonymous enum

Enumerator
kCCM32K_32kOscReadyStatusFlag	Indicates the 32kHz crystal oscillator is stable.
kCCM32K_32kOscActiveStatusFlag	Indicates the 32kHz crystal oscillator is active and in use.
kCCM32K_32kFroActiveStatusFlag	Indicates the 32kHz free running oscillator is active and in use.
kCCM32K_ClockDetectStatusFlag	Indicates the clock monitor has detected an error.

enum ccm32k_state_t

Enumerator
kCCM32K_Both32kFro32kOscDisabled	Indicates both 32kHz free running oscillator and 32kHz crystal oscillator are disabled.
kCCM32K_Only32kFroEnabled	Indicates only 32kHz free running oscillator is enabled.
kCCM32K_Only32kOscEnabled	Indicates only 32kHz crystal oscillator is enabled.
kCCM32K_Both32kFro32kOscEnabled	Indicates both 32kHz free running oscillator and 32kHz crystal oscillator are enabled.

enum ccm32k_clock_source_t

Enumerator
kCCM32K_ClockSourceNone	None clock source.
kCCM32K_ClockSource32kFro	32kHz free running oscillator is the clock source.
kCCM32K_ClockSource32kOsc	32kHz crystal oscillator is the clock source.

enum ccm32k_clock_monitor_freq_trim_value_t

Enumerator
kCCM32K_ClockMonitor2CycleAssert	Clock monitor asserts 2 cycle after expected edge (assert after 10 cycles with no edge).
kCCM32K_ClockMonitor4CycleAssert	Clock monitor asserts 4 cycle after expected edge (assert after 12 cycles with no edge).
kCCM32K_ClockMonitor6CycleAssert	Clock monitor asserts 6 cycle after expected edge (assert after 14 cycles with no edge).
kCCM32K_ClockMonitor8CycleAssert	Clock monitor asserts 8 cycle after expected edge (assert after 16 cycles with no edge).

enum ccm32k_clock_monitor_divide_trim_value_t

Enumerator
kCCM32K_ClockMonitor_1kHzFro32k_1kHzOsc32k	Clock monitor operates at 1 kHz for both FRO32K and OSC32K.
kCCM32K_ClockMonitor_64HzFro32k_1kHzOsc32k	Clock monitor operates at 64 Hz for FRO32K and clock monitor operates at 1 kHz for OSC32K.
kCCM32K_ClockMonitor_1KHzFro32k_64HzOsc32k	Clock monitor operates at 1K Hz for FRO32K and clock monitor operates at 64 Hz for OSC32K.
kCCM32K_ClockMonitor_64HzFro32k_64HzOsc32k	Clock monitor operates at 64 Hz for FRO32K and clock monitor operates at 64 Hz for OSC32K.

enum ccm32k_clock_source_select_t

Enumerator
kCCM32K_ClockSourceSelectFro32k	FRO32K clock output is selected as clock source.
kCCM32K_ClockSourceSelectOsc32k	OSC32K clock output is selected as clock source.

enum ccm32k_clock_output_peripheral_t

Enumerator
kCCM32K_ClockOutToRtc	32kHz clock output to RTC.
kCCM32K_ClockOutToRfmc	32kHz clock output to Rfmc.
kCCM32K_ClockOutToNbu	32kHz clock output to NBU.
kCCM32K_ClockOutToWuuRmcPortD	32kHz clock output to WUU/RMC/PORTD.
kCCM32K_ClockOutToOtherModules	32kHz clock output to Other modules.

Function Documentation

static void CCM32K_Enable32kFro	(	CCM32K_Type *	base,
		bool	enable
	)

inlinestatic

Note: There is a start up time before clocks are output from the FRO.

Parameters

base	CCM32K peripheral base address.
enable	Boolean value to enable or disable the 32kHz free-running oscillator. true – Enable 32kHz free-running oscillator. false – Disable 32kHz free-running oscillator.

static void CCM32K_Lock32kFroWriteAccess ( CCM32K_Type * base )

inlinestatic

Parameters

base	CCM32K peripheral base address.

static uint16_t CCM32K_Get32kFroTrimValue ( CCM32K_Type * base )

inlinestatic

Parameters

base	CCM32K peripheral base address.

Returns: The current trim value.

void CCM32K_Set32kFroTrimValue	(	CCM32K_Type *	base,
		uint16_t	trimValue
	)

Note: The frequency is decreased monotonically when the trimValue is changed progressively from 0x0U to 0x7FFU.; If the FRO32 is enabled before invoking this function, then in this function the FRO32 will be disabled, after updating trim value the FRO32 will be re-enabled.

Parameters

base	CCM32K peripheral base address.
trimValue	The frequency trim value.

static void CCM32K_Disable32kFroIFRLoad	(	CCM32K_Type *	base,
		bool	disable
	)

inlinestatic

Parameters

base	CCM32K peripheral base address.
disable	Boolean value to disable or enable IFR loading function. true – Disable IFR loading function. false – Enable IFR loading function.

static void CCM32K_Lock32kFroTrimWriteAccess ( CCM32K_Type * base )

inlinestatic

Parameters

base	CCM32K peripheral base address.

void CCM32K_Set32kOscConfig	(	CCM32K_Type *	base,
		ccm32k_osc_mode_t	mode,
		const ccm32k_osc_config_t *	config
	)

Note: When the mode selected as kCCM32K_Disable32kHzCrystalOsc or kCCM32K_Bypass32kHzCrystalOsc the parameter config is useless, so it can be set as "NULL".

Parameters

base	CCM32K peripheral base address.
mode	The mode of 32k crystal oscillator.
config	The pointer to the structure ccm32k_osc_config_t.

static void CCM32K_Lock32kOscWriteAccess ( CCM32K_Type * base )

inlinestatic

Parameters

base	CCM32K peripheral base address.

static void CCM32K_EnableClockMonitor	(	CCM32K_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	CCM32K peripheral base address.
enable	Used to enable/disable clock monitor. turn Enable clock monitor. false Disable clock monitor.

static void CCM32K_SetClockMonitorFreqTrimValue	(	CCM32K_Type *	base,
		ccm32k_clock_monitor_freq_trim_value_t	trimValue
	)

inlinestatic

Parameters

base	CCM32K peripheral base address.
trimValue	Clock minitor frequency trim value, please refer to ccm32k_clock_monitor_freq_trim_value_t.

static void CCM32K_SetClockMonitorDivideTrimValue	(	CCM32K_Type *	base,
		ccm32k_clock_monitor_divide_trim_value_t	trimValue
	)

inlinestatic

Parameters

base	CCM32K peripheral base address.
trimValue	Clock minitor divide trim value, please refer to ccm32k_clock_monitor_divide_trim_value_t.

void CCM32K_SetClockMonitorConfig	(	CCM32K_Type *	base,
		const ccm32k_clock_monitor_config_t *	config
	)

Parameters

base	CCM32K peripheral base address.
config	Pointer to ccm32k_clock_monitor_config_t structure.

static void CCM32K_LockClockMonitorWriteAccess ( CCM32K_Type * base )

inlinestatic

Parameters

base	CCM32K peripheral base address.

static void CCM32K_EnableCLKOutToPeripherals	(	CCM32K_Type *	base,
		uint8_t	peripheralMask
	)

inlinestatic

Parameters

base	CCM32K peripheral base address.
peripheralMask	The mask of peripherals to enable 32kHz clock output, should be the OR'ed value of ccm32k_clock_output_peripheral_t.

static void CCM32K_DisableCLKOutToPeripherals	(	CCM32K_Type *	base,
		uint8_t	peripheralMask
	)

inlinestatic

Parameters

base	CCM32K peripheral base address.
peripheralMask	The mask of peripherals to disable 32kHz clock output, should be the OR'ed value of ccm32k_clock_output_peripheral_t.

static void CCM32K_SelectClockSource	(	CCM32K_Type *	base,
		ccm32k_clock_source_select_t	clockSource
	)

inlinestatic

Parameters

base	CCM32K peripheral base address.
clockSource	Used to select clock source, please refer to ccm32k_clock_source_select_t for details.

static void CCM32K_LockClockGateWriteAccess ( CCM32K_Type * base )

inlinestatic

Parameters

base	CCM32K peripheral base address.

static uint32_t CCM32K_GetStatusFlag ( CCM32K_Type * base )

inlinestatic

Parameters

base	CCM32K peripheral base address.

Returns: The status flag of the current node. The enumerator of status flags have been provided, please see the Enumerations title for details.

ccm32k_state_t CCM32K_GetCurrentState ( CCM32K_Type * base )

Parameters

base	CCM32K peripheral base address.

Returns: The CCM32K's current state, please refer to ccm32k_state_t for details.

ccm32k_clock_source_t CCM32K_GetClockSource ( CCM32K_Type * base )

Parameters

base	CCM32K peripheral base address.

Return values

kCCM32K_ClockSourceNone	The none clock source is selected.
kCCM32K_ClockSource32kFro	32kHz free-running oscillator is selected as clock source.
kCCM32K_ClockSource32kOsc	32kHz crystal oscillator is selected as clock source..

Overview

Control 32kHz free-running oscillator

Control 32kHz crystal oscillator

Data Structures

Enumerations

Driver version

32kHz Free-running Oscillator Interfaces

32kHz Crystal Oscillator Interfaces

Clock Monitor Control Interfaces

Clock Gate Control Interfaces

Status Interface

State/Clock Source Interfaces

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation