Overview

The Kinetis SDK provides the Hardware Timer Manager driver for various timer modules.

Modules
	Hardware Timer Manager Driver

	Hardware Timer Manager Interrupt handlers

Files
file	fsl_hwtimer.h

Data Structures
struct	hwtimer_ptr_t
	HwTimer structure. More...

struct	hwtimer_time_ptr_t
	Hwtimer_time structure. More...

struct	hwtimer_devif_ptr_t
	hwtimer_devif structure. More...

Macros
#define	HWTIMER_LL_CONTEXT_LEN 5U
	HwTimer low level context data length definition.

Typedefs
typedef void(*	hwtimer_callback_t )(void *p)
	Definition for low level context data length.

typedef _hwtimer_error_code_t(*	hwtimer_devif_init_t )(hwtimer_t hwtimer, uint32_t id, void data)
	Type defines initialization function for devif structure.

typedef _hwtimer_error_code_t(*	hwtimer_devif_deinit_t )(hwtimer_t *hwtimer)
	Type defines deinitialization function for devif structure.

typedef _hwtimer_error_code_t(*	hwtimer_devif_set_div_t )(hwtimer_t *hwtimer, uint32_t period)
	Type defines set_div function for devif structure.

typedef _hwtimer_error_code_t(*	hwtimer_devif_start_t )(hwtimer_t *hwtimer)
	Type defines start function for devif structure.

typedef _hwtimer_error_code_t(*	hwtimer_devif_stop_t )(hwtimer_t *hwtimer)
	Type defines stop function for devif structure.

typedef _hwtimer_error_code_t(*	hwtimer_devif_reset_t )(hwtimer_t *hwtimer)
	Type defines reset function for devif structure.

typedef _hwtimer_error_code_t(*	hwtimer_devif_get_time_t )(hwtimer_t hwtimer, hwtimer_time_t time)
	Type defines get_time function for devif structure.

Enumerations
enum	_hwtimer_error_code_t { kHwtimerSuccess, kHwtimerInvalidInput, kHwtimerInvalidPointer, kHwtimerClockManagerError, kHwtimerRegisterHandlerError, kHwtimerUnknown }
	HwTimer error codes definition. More...

Functions
_hwtimer_error_code_t	HWTIMER_SYS_Init (hwtimer_t hwtimer, const hwtimer_devif_t kDevif, uint32_t id, void *data)
	Initializes a caller allocated structure according to given parameters. More...

_hwtimer_error_code_t	HWTIMER_SYS_Deinit (hwtimer_t *hwtimer)
	Deinitializes the HwTimer. More...

_hwtimer_error_code_t	HWTIMER_SYS_SetPeriod (hwtimer_t *hwtimer, uint32_t period)
	Sets the period of the HwTimer. More...

uint32_t	HWTIMER_SYS_GetPeriod (hwtimer_t *hwtimer)
	Gets the period of the HwTimer. More...

_hwtimer_error_code_t	HWTIMER_SYS_Start (hwtimer_t *hwtimer)
	Enables the timer and leaves it running. More...

_hwtimer_error_code_t	HWTIMER_SYS_Stop (hwtimer_t *hwtimer)
	The timer stops counting after this function is called. More...

uint32_t	HWTIMER_SYS_GetModulo (hwtimer_t *hwtimer)
	The function returns period of the timer in sub-ticks. More...

_hwtimer_error_code_t	HWTIMER_SYS_GetTime (hwtimer_t hwtimer, hwtimer_time_t time)
	The function reads the current value of the HwTimer. More...

uint32_t	HWTIMER_SYS_GetTicks (hwtimer_t *hwtimer)
	The function reads the current value of the HwTimer. More...

_hwtimer_error_code_t	HWTIMER_SYS_RegisterCallback (hwtimer_t hwtimer, hwtimer_callback_t callbackFunc, void callbackData)
	Registers function to be called when the timer expires. More...

_hwtimer_error_code_t	HWTIMER_SYS_BlockCallback (hwtimer_t *hwtimer)
	The function is used to block callbacks in circumstances when execution of the callback function is undesired. More...

_hwtimer_error_code_t	HWTIMER_SYS_UnblockCallback (hwtimer_t *hwtimer)
	The function is used to unblock previously blocked callbacks. More...

_hwtimer_error_code_t	HWTIMER_SYS_CancelCallback (hwtimer_t *hwtimer)
	The function cancels pending callback, if any. More...

Data Structure Documentation

struct hwtimer_t

This structure defines a HwTimer. The context structure is passed to all API functions (besides other parameters).

Warning: Application should not access members of this structure directly.

See Also: HWTIMER_SYS_init; HWTIMER_SYS_deinit; HWTIMER_SYS_start; HWTIMER_SYS_stop; HWTIMER_SYS_set_period; HWTIMER_SYS_get_period; HWTIMER_SYS_get_modulo; HWTIMER_SYS_get_time; HWTIMER_SYS_get_ticks; HWTIMER_SYS_callback_reg; HWTIMER_SYS_callback_block; HWTIMER_SYS_callback_unblock; HWTIMER_SYS_callback_cancel

Data Fields
const struct Hwtimer_devif *	devif
	Pointer to a device interface structure.

uint32_t	clockFreq
	Timer's source clock frequency.

uint32_t	divider
	Actual total divider.

uint32_t	modulo
	Determine how many sub ticks are in one tick.

volatile uint64_t	ticks
	Number of elapsed ticks.

hwtimer_callback_t	callbackFunc
	Function pointer to be called when the timer expires. More...

void *	callbackData
	Arbitrary pointer passed as parameter to the callback function. More...

volatile int	callbackPending
	Indicate pending callback. More...

int	callbackBlocked
	Indicate blocked callback. More...

uint32_t	llContext [HWTIMER_LL_CONTEXT_LEN]
	Private storage locations for arbitrary data keeping the context of the lower layer driver. More...

Field Documentation

hwtimer_callback_t hwtimer_ptr_t::callbackFunc

void* hwtimer_ptr_t::callbackData

volatile int hwtimer_ptr_t::callbackPending

If the timer overflows when callbacks are blocked the callback becomes pending.

int hwtimer_ptr_t::callbackBlocked

uint32_t hwtimer_ptr_t::llContext[HWTIMER_LL_CONTEXT_LEN]

struct hwtimer_time_t

HwTimer time structure represents a time stamp consisting of timer elapsed periods (TICKS) and current value of the timer counter (subTicks).

See Also: HWTIMER_SYS_GetTime

Data Fields
uint64_t	ticks
	Ticks of timer.

uint32_t	subTicks
	Sub ticks of timer.

struct hwtimer_devif_t

Each low layer driver exports an instance of this structure initialized with pointers to API functions that the driver implements. The functions should be declared as static (not exported directly).

See Also: HWTIMER_SYS_Init; HWTIMER_SYS_Deinit

Data Fields
hwtimer_devif_init_t	init
	Function pointer to lower layer initialization.

hwtimer_devif_deinit_t	deinit
	Function pointer to lower layer de-initialization.

hwtimer_devif_set_div_t	setDiv
	Function pointer to lower layer set divider functionality.

hwtimer_devif_start_t	start
	Function pointer to lower layer start functionality.

hwtimer_devif_stop_t	stop
	Function pointer to lower layer stop functionality.

hwtimer_devif_get_time_t	getTime
	Function pointer to lower layer get time functionality.

Enumeration Type Documentation

enum _hwtimer_error_code_t

Enumerator
kHwtimerSuccess	success
kHwtimerInvalidInput	invalid input parameter
kHwtimerInvalidPointer	invalid pointer
kHwtimerClockManagerError	clock manager return error
kHwtimerRegisterHandlerError	Interrupt handler registration returns error.
kHwtimerUnknown	unknown error

Function Documentation

_hwtimer_error_code_t HWTIMER_SYS_Init	(	hwtimer_t *	hwtimer,
		const hwtimer_devif_t *	kDevif,
		uint32_t	id,
		void *	data
	)

The device interface pointer determines the low layer driver to be used. Device interface structure is exported by each low layer driver and is opaque to the applications. See a chapter about the low layer driver below for details. Meaning of the numerical identifier varies depending on the low layer driver used. Typically, it identifies a particular timer channel to initialize. The initialization function has to be called prior to using any other API function.

Parameters

hwtimer	[out] Returns initialized HwTimer structure handle.
kDevif	[in] Structure determines low layer driver to be used.
id	[in] Numerical identifier of the timer.
data	[in] Specific data for low level of interrupt.

Returns: success or an error code returned from low level initialization function.

Return values

kHwtimerSuccess	Success
kHwtimerInvalidInput	When input parameter HwTimer is a NULL pointer
kHwtimerInvalidPointer	When device structure points to NULL.

Warning: The initialization function has to be called prior using any other API function.

See Also: HWTIMER_SYS_deinit; HWTIMER_SYS_start; HWTIMER_SYS_stop

_hwtimer_error_code_t HWTIMER_SYS_Deinit ( hwtimer_t * hwtimer )

Calls the lower layer stop function to stop the timer. Then, calls the low layer de-initialization function and afterwards invalidates HwTimer structure by clearing it.

Parameters

hwtimer [in] Pointer to HwTimer structure.

Returns: success or an error code returned from low level DEINIT function.

Return values

kHwtimerSuccess	Success
kHwtimerInvalidInput	When input parameter HwTimer is a NULL pointer
kHwtimerInvalidPointer	When device structure points to NULL.

See Also: HWTIMER_SYS_Init; HWTIMER_SYS_Start; HWTIMER_SYS_Stop

_hwtimer_error_code_t HWTIMER_SYS_SetPeriod	(	hwtimer_t *	hwtimer,
		uint32_t	period
	)

The function provides a way to set up the timer to a desired period specified in microseconds. Calls the low layer driver to set up the timer divider according to the specified period.

Parameters

hwtimer	[in] Pointer to HwTimer structure.
period	[in] Required period of timer in micro seconds.

Returns: success or an error code returned from low level SETDIV function.

Return values

kHwtimerSuccess	Success
kHwtimerInvalidInput	When input parameter HwTimer or his device structure are NULL pointers.
kHwtimerInvalidPointer	When low level SETDIV function point to NULL.
kHwtimerClockManagerError	When Clock manager returns error.

See Also: HWTIMER_SYS_GetPeriod; HWTIMER_SYS_GetModulo; HWTIMER_SYS_GetTime; HWTIMER_SYS_GetTicks

uint32_t HWTIMER_SYS_GetPeriod ( hwtimer_t * hwtimer )

The function returns the current period of the timer in microseconds calculated from the base frequency and actual divider settings of the timer.

Parameters

hwtimer [in] Pointer to HwTimer structure.

Returns: already set period of HwTimer.

Return values

0	Input parameter HwTimer is NULL pointer or clock manager returns error.

See Also: HWTIMER_SYS_SetPeriod; HWTIMER_SYS_GetModulo; HWTIMER_SYS_GetTime; HWTIMER_SYS_GetTicks

_hwtimer_error_code_t HWTIMER_SYS_Start ( hwtimer_t * hwtimer )

The timer starts counting a new period generating interrupts every time the timer rolls over.

Parameters

hwtimer [in] Pointer to HwTimer structure.

Returns: success or an error code returned from low level START function.

Return values

kHwtimerSuccess	Success
kHwtimerInvalidInput	When input parameter HwTimer is a NULL pointer
kHwtimerInvalidPointer	When device structure points to NULL.

See Also: HWTIMER_SYS_Init; HWTIMER_SYS_Deinit; HWTIMER_SYS_Stop

_hwtimer_error_code_t HWTIMER_SYS_Stop ( hwtimer_t * hwtimer )

Pending interrupts and callbacks are cancelled.

Parameters

hwtimer [in] Pointer to HwTimer structure.

Returns: success or an error code returned from low level STOP function.

Return values

kHwtimerSuccess	Success
kHwtimerInvalidInput	When input parameter HwTimer is a NULL pointer
kHwtimerInvalidPointer	When device structure points to NULL.

See Also: HWTIMER_SYS_Init; HWTIMER_SYS_Deinit; HWTIMER_SYS_Start

uint32_t HWTIMER_SYS_GetModulo ( hwtimer_t * hwtimer )

It is typically called after HWTIMER_SYS_SetPeriod() to obtain actual resolution of the timer in the current configuration.

Parameters

hwtimer [in] Pointer to HwTimer structure.

Returns: resolution of HwTimer.

Return values

0	Input parameter HwTimer is NULL pointer.

See Also: HWTIMER_SYS_SetPeriod; HWTIMER_SYS_GetPeriod; HWTIMER_SYS_GetTime; HWTIMER_SYS_GetTicks

_hwtimer_error_code_t HWTIMER_SYS_GetTime	(	hwtimer_t *	hwtimer,
		hwtimer_time_t *	time
	)

Elapsed periods(ticks) and current value of the timer counter (sub-ticks) are filled into the Hwtimer_time structure. The sub-ticks number always counts up and is reset to zero when the timer overflows regardless of the counting direction of the underlying device.

Parameters

hwtimer	[in] Pointer to HwTimer structure.
time	[out] Pointer to time structure. This value is filled with current value of the timer.

Returns: success or an error code returned from low level GET_TIME function.

Return values

kHwtimerSuccess	Success
kHwtimerInvalidInput	When input parameter HwTimer or input parameter time are NULL pointers.
kHwtimerInvalidPointer	When device structure points to NULL.

See Also: HWTIMER_SYS_SetPeriod; HWTIMER_SYS_GetPeriod; HWTIMER_SYS_GetModulo; HWTIMER_SYS_GetTicks

uint32_t HWTIMER_SYS_GetTicks ( hwtimer_t * hwtimer )

The returned value corresponds to the lower 32 bits of elapsed periods (ticks). The value is guaranteed to be obtained without needing to mask timer interrupt. Lower layer driver is not involved at all and calling this function is considerably faster than HWTIMER_SYS_GetTime.

Parameters

hwtimer [in] Pointer to HwTimer structure.

Returns: low 32 bits of 64 bit tick value.

Return values

0	When input parameter HwTimer is NULL pointer.

See Also: HWTIMER_SYS_SetPeriod; HWTIMER_SYS_GetPeriod; HWTIMER_SYS_GetModulo; HWTIMER_SYS_GetTime

_hwtimer_error_code_t HWTIMER_SYS_RegisterCallback	(	hwtimer_t *	hwtimer,
		hwtimer_callback_t	callbackFunc,
		void *	callbackData
	)

The callback_data is arbitrary pointer passed as parameter to the callback function.

Parameters

hwtimer	[in] Pointer to HwTimer structure.
callbackFunc	[in] Function pointer to be called when the timer expires.
callbackData	[in] Data pointer for the function callback_func.

Returns: success or an error code

Return values

kHwtimerInvalidInput	When input parameter HwTimer is NULL pointer.
kHwtimerSuccess	When registration callback succeed.

Warning: This function must not be called from a callback routine.

See Also: HWTIMER_SYS_BlockCallback; HWTIMER_SYS_UnblockCallback; HWTIMER_SYS_CancelCallback

_hwtimer_error_code_t HWTIMER_SYS_BlockCallback ( hwtimer_t * hwtimer )

If the timer overflows when callbacks are blocked the callback becomes pending.

Parameters

hwtimer [in] Pointer to HwTimer structure.

Returns: success or an error code

Return values

kHwtimerInvalidInput	When input parameter HwTimer is NULL pointer.
kHwtimerSuccess	When callback block succeed.

Warning: This function must not be called from a callback routine.

See Also: HWTIMER_SYS_RegCallback; HWTIMER_SYS_UnblockCallback; HWTIMER_SYS_CancelCallback

_hwtimer_error_code_t HWTIMER_SYS_UnblockCallback ( hwtimer_t * hwtimer )

If there is a callback pending, it gets immediately executed. This function must not be called from a callback routine (it does not make sense to do so anyway as callback function never gets executed while callbacks are blocked).

Parameters

hwtimer [in] Pointer to HwTimer structure.

Returns: success or an error code

Return values

kHwtimerInvalidInput	When input parameter HwTimer is NULL pointer.
kHwtimerSuccess	When callback unblock succeed.

Warning: This function must not be called from a callback routine.

See Also: HWTIMER_SYS_RegCallback; HWTIMER_SYS_BlockCallback; HWTIMER_SYS_CancelCallback

_hwtimer_error_code_t HWTIMER_SYS_CancelCallback ( hwtimer_t * hwtimer )

Parameters

hwtimer [in] Pointer to HwTimer structure.

Returns: success or an error code

Return values

kHwtimerInvalidInput	When input parameter HwTimer is NULL pointer.
kHwtimerSuccess	When callback cancel succeed.

Warning: This function must not be called from a callback routine (it does not make sense to do so anyway as callback function never gets executed while callbacks are blocked).

See Also: HWTIMER_SYS_RegCallback; HWTIMER_SYS_BlockCallback; HWTIMER_SYS_UnblockCallback

Overview

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Data Fields

Enumeration Type Documentation

Function Documentation