Timer Interface

Detailed Description

Interface for timer functions.

Summary

The general timer interface provides standard timer functionality including periodic mode, one-shot mode, PWM output, and free-running timer mode. After each timer cycle (overflow or underflow), an interrupt can be triggered.

If an instance supports output compare mode, it is provided in the extension configuration timer_on_<instance>_cfg_t defined in r_<instance>.h.

Data Structures
struct	timer_callback_args_t
struct	timer_info_t
struct	timer_status_t
struct	timer_cfg_t
struct	timer_api_t
struct	timer_instance_t

Typedefs
typedef void	timer_ctrl_t

Enumerations
enum	timer_event_t
enum	timer_variant_t
enum	timer_compare_match_t
enum	timer_state_t
enum	timer_mode_t
enum	timer_direction_t
enum	timer_source_div_t

---

Data Structure Documentation

timer_callback_args_t

struct timer_callback_args_t

Callback function parameter data

Data Fields
void const *	p_context	Placeholder for user data. Set in timer_api_t::open function in timer_cfg_t.
timer_event_t	event	The event can be used to identify what caused the callback.
uint32_t	capture	Most recent capture, only valid if event is TIMER_EVENT_CAPTURE_A or TIMER_EVENT_CAPTURE_B.

timer_info_t

struct timer_info_t

Timer information structure to store various information for a timer resource

Data Fields
timer_direction_t	count_direction	Clock counting direction of the timer.
uint32_t	clock_frequency	Clock frequency of the timer counter.
uint32_t	period_counts	Period in raw timer counts. Note For triangle wave PWM modes, the full period is double this value.

timer_status_t

struct timer_status_t

Current timer status.

Data Fields
uint32_t	counter	Current counter value.
timer_state_t	state	Current timer state (running or stopped)

timer_cfg_t

struct timer_cfg_t

User configuration structure, used in open function

Data Fields
timer_mode_t	mode
	Select enumerated value from timer_mode_t.
uint32_t	period_counts
	Period in raw timer counts.
timer_source_div_t	source_div
	Source clock divider.
uint32_t	duty_cycle_counts
	Duty cycle in counts.
uint8_t	channel
uint8_t	cycle_end_ipl
	Cycle end interrupt priority.
IRQn_Type	cycle_end_irq
	Cycle end interrupt.
void(*	p_callback )(timer_callback_args_t *p_args)
void const *	p_context
void const *	p_extend
	Extension parameter for hardware specific settings.

Field Documentation

channel

uint8_t timer_cfg_t::channel

Select a channel corresponding to the channel number of the hardware.

p_callback

void(* timer_cfg_t::p_callback) (timer_callback_args_t *p_args)

Callback provided when a timer ISR occurs. Set to NULL for no CPU interrupt.

p_context

void const* timer_cfg_t::p_context

Placeholder for user data. Passed to the user callback in timer_callback_args_t.

timer_api_t

struct timer_api_t

Timer API structure. General timer functions implemented at the HAL layer follow this API.

Data Fields
fsp_err_t(*	open )(timer_ctrl_t *const p_ctrl, timer_cfg_t const *const p_cfg)
fsp_err_t(*	start )(timer_ctrl_t *const p_ctrl)
fsp_err_t(*	stop )(timer_ctrl_t *const p_ctrl)
fsp_err_t(*	reset )(timer_ctrl_t *const p_ctrl)
fsp_err_t(*	enable )(timer_ctrl_t *const p_ctrl)
fsp_err_t(*	disable )(timer_ctrl_t *const p_ctrl)
fsp_err_t(*	periodSet )(timer_ctrl_t *const p_ctrl, uint32_t const period)
fsp_err_t(*	dutyCycleSet )(timer_ctrl_t *const p_ctrl, uint32_t const duty_cycle_counts, uint32_t const pin)
fsp_err_t(*	compareMatchSet )(timer_ctrl_t *const p_ctrl, uint32_t const compare_match_value, timer_compare_match_t const match_channel)
fsp_err_t(*	infoGet )(timer_ctrl_t *const p_ctrl, timer_info_t *const p_info)
fsp_err_t(*	statusGet )(timer_ctrl_t *const p_ctrl, timer_status_t *const p_status)
fsp_err_t(*	callbackSet )(timer_ctrl_t *const p_ctrl, void(*p_callback)(timer_callback_args_t *), void const *const p_context, timer_callback_args_t *const p_callback_memory)
fsp_err_t(*	close )(timer_ctrl_t *const p_ctrl)

Field Documentation

open

fsp_err_t(* timer_api_t::open) (timer_ctrl_t *const p_ctrl, timer_cfg_t const *const p_cfg)

Initial configuration.

Parameters

[in]	p_ctrl	Pointer to control block. Must be declared by user. Elements set here.
[in]	p_cfg	Pointer to configuration structure. All elements of this structure must be set by user.

start

fsp_err_t(* timer_api_t::start) (timer_ctrl_t *const p_ctrl)

Start the counter.

Parameters

[in]

p_ctrl

Control block set in timer_api_t::open call for this timer.

stop

fsp_err_t(* timer_api_t::stop) (timer_ctrl_t *const p_ctrl)

Stop the counter.

Parameters

[in]

p_ctrl

Control block set in timer_api_t::open call for this timer.

reset

fsp_err_t(* timer_api_t::reset) (timer_ctrl_t *const p_ctrl)

Reset the counter to the initial value.

Parameters

[in]

p_ctrl

Control block set in timer_api_t::open call for this timer.

enable

fsp_err_t(* timer_api_t::enable) (timer_ctrl_t *const p_ctrl)

Enables input capture.

Parameters

[in]

p_ctrl

Control block set in timer_api_t::open call for this timer.

disable

fsp_err_t(* timer_api_t::disable) (timer_ctrl_t *const p_ctrl)

Disables input capture.

Parameters

[in]

p_ctrl

Control block set in timer_api_t::open call for this timer.

periodSet

fsp_err_t(* timer_api_t::periodSet) (timer_ctrl_t *const p_ctrl, uint32_t const period)

Set the time until the timer expires. See implementation for details of period update timing.

Note

Timer expiration may or may not generate a CPU interrupt based on how the timer is configured in timer_api_t::open.

Parameters

[in]	p_ctrl	Control block set in timer_api_t::open call for this timer.
[in]	period	Time until timer should expire.

dutyCycleSet

fsp_err_t(* timer_api_t::dutyCycleSet) (timer_ctrl_t *const p_ctrl, uint32_t const duty_cycle_counts, uint32_t const pin)

Sets the number of counts for the pin level to be high. If the timer is counting, the updated duty cycle is reflected after the next timer expiration.

Parameters

[in]	p_ctrl	Control block set in timer_api_t::open call for this timer.
[in]	duty_cycle_counts	Time until duty cycle should expire.
[in]	pin	Which output pin to update. See implementation for details.

compareMatchSet

fsp_err_t(* timer_api_t::compareMatchSet) (timer_ctrl_t *const p_ctrl, uint32_t const compare_match_value, timer_compare_match_t const match_channel)

Set a compare match value in raw counts.

Parameters

[in]	p_ctrl	Control block set in timer_api_t::open call for this timer.
[in]	compare_match_value	Timer value to trigger a compare match event.
[in]	match_channel	Which channel to update.

infoGet

fsp_err_t(* timer_api_t::infoGet) (timer_ctrl_t *const p_ctrl, timer_info_t *const p_info)

Stores timer information in p_info.

Parameters

[in]	p_ctrl	Control block set in timer_api_t::open call for this timer.
[out]	p_info	Collection of information for this timer.

statusGet

fsp_err_t(* timer_api_t::statusGet) (timer_ctrl_t *const p_ctrl, timer_status_t *const p_status)

Get the current counter value and timer state and store it in p_status.

Parameters

[in]	p_ctrl	Control block set in timer_api_t::open call for this timer.
[out]	p_status	Current status of this timer.

callbackSet

fsp_err_t(* timer_api_t::callbackSet) (timer_ctrl_t *const p_ctrl, void(*p_callback)(timer_callback_args_t *), void const *const p_context, timer_callback_args_t *const p_callback_memory)

Specify callback function and optional context pointer and working memory pointer.

Parameters

[in]	p_ctrl	Control block set in timer_api_t::open call for this timer.
[in]	p_callback	Callback function to register
[in]	p_context	Pointer to send to callback function
[in]	p_working_memory	Pointer to volatile memory where callback structure can be allocated. Callback arguments allocated here are only valid during the callback.

close

fsp_err_t(* timer_api_t::close) (timer_ctrl_t *const p_ctrl)

Allows driver to be reconfigured and may reduce power consumption.

Parameters

[in]

p_ctrl

Control block set in timer_api_t::open call for this timer.

timer_instance_t

struct timer_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
timer_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
timer_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
timer_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

timer_ctrl_t

typedef void timer_ctrl_t

Timer control block. Allocate an instance specific control block to pass into the timer API calls.

Enumeration Type Documentation

timer_event_t

enum timer_event_t

Events that can trigger a callback function

Enumerator
TIMER_EVENT_CYCLE_END	Requested timer delay has expired or timer has wrapped around.
TIMER_EVENT_HIGHER_8BIT_CYCLE_END	Requested higher 8-bit timer has expired.
TIMER_EVENT_CAPTURE_EDGE	A capture has occurred when detecting edge.
TIMER_EVENT_SLAVE_CYCLE_END	Requested timer pulse width (One-shot) or duty cycle (PWM) has expired.
TIMER_EVENT_MASTER_CYCLE_END	Requested timer delay (One-shot) or period (PWM) has expired.
TIMER_EVENT_CYCLE_END	Requested timer delay has expired or timer has wrapped around.
TIMER_EVENT_HIGHER_8BIT_CYCLE_END	Requested higher 8-bit timer has expired.
TIMER_EVENT_CAPTURE_EDGE	A capture has occurred when detecting edge.
TIMER_EVENT_SLAVE_CYCLE_END	Requested timer pulse width (One-shot) or duty cycle (PWM) has expired.
TIMER_EVENT_MASTER_CYCLE_END	Requested timer delay (One-shot) or period (PWM) has expired.
TIMER_EVENT_CYCLE_END	Requested timer delay has expired or timer has wrapped around.
TIMER_EVENT_CREST	Timer crest event (counter is at a maximum, triangle-wave PWM only)
TIMER_EVENT_CAPTURE_A	A capture has occurred on signal A.
TIMER_EVENT_CAPTURE_B	A capture has occurred on signal B.
TIMER_EVENT_TROUGH	Timer trough event (counter is 0, triangle-wave PWM only.
TIMER_EVENT_COMPARE_A	A compare has occurred on signal A.
TIMER_EVENT_COMPARE_B	A compare has occurred on signal B.
TIMER_EVENT_COMPARE_C	A compare has occurred on signal C.
TIMER_EVENT_COMPARE_D	A compare has occurred on signal D.
TIMER_EVENT_COMPARE_E	A compare has occurred on signal E.
TIMER_EVENT_COMPARE_F	A compare has occurred on signal F.
TIMER_EVENT_DEAD_TIME	Dead time event.

timer_variant_t

enum timer_variant_t

Timer variant types.

Enumerator
TIMER_VARIANT_32_BIT	32-bit timer
TIMER_VARIANT_16_BIT	16-bit timer

timer_compare_match_t

enum timer_compare_match_t

Options for storing compare match value

Enumerator
TIMER_COMPARE_MATCH_A	Compare match A value.
TIMER_COMPARE_MATCH_B	Compare match B value.
TIMER_COMPARE_MATCH_C	Compare match C value.
TIMER_COMPARE_MATCH_D	Compare match D value.
TIMER_COMPARE_MATCH_E	Compare match E value.
TIMER_COMPARE_MATCH_F	Compare match F value.
TIMER_COMPARE_MATCH_G	Compare match G value.
TIMER_COMPARE_MATCH_H	Compare match H value.

timer_state_t

enum timer_state_t

Possible status values returned by timer_api_t::statusGet.

Enumerator
TIMER_STATE_STOPPED	Timer is stopped.
TIMER_STATE_COUNTING	Timer is running.
TIMER_STATE_UNKNOWN	Timer state could not be defined.

timer_mode_t

enum timer_mode_t

Timer operational modes

Enumerator
TIMER_MODE_8_BIT_COUNTER	8-bit counter mode
TIMER_MODE_16_BIT_COUNTER	16-bit counter mode
TIMER_MODE_32_BIT_COUNTER	32-bit counter mode
TIMER_MODE_16_BIT_CAPTURE	16-bit capture mode
TIMER_MODE_PERIODIC	Timer restarts after period elapses.
TIMER_MODE_ONE_SHOT	Timer stops after period elapses.
TIMER_MODE_PWM	Timer generates saw-wave PWM output.
TIMER_MODE_8_BIT_COUNTER	8-bit counter mode
TIMER_MODE_16_BIT_COUNTER	16-bit counter mode
TIMER_MODE_32_BIT_COUNTER	32-bit counter mode
TIMER_MODE_16_BIT_CAPTURE	16-bit capture mode
TIMER_MODE_PERIODIC	Timer restarts after period elapses.
TIMER_MODE_ONE_SHOT	Timer stops after period elapses.
TIMER_MODE_PWM	Timer generates saw-wave PWM output.
TIMER_MODE_PERIODIC	Timer restarts after period elapses.
TIMER_MODE_ONE_SHOT	Timer stops after period elapses.
TIMER_MODE_PWM	Timer generates saw-wave PWM output.
TIMER_MODE_ONE_SHOT_PULSE	Saw-wave one-shot pulse mode (fixed buffer operation).
TIMER_MODE_TRIANGLE_WAVE_SYMMETRIC_PWM	Timer generates symmetric triangle-wave PWM output.
TIMER_MODE_TRIANGLE_WAVE_ASYMMETRIC_PWM	Timer generates asymmetric triangle-wave PWM output.
TIMER_MODE_TRIANGLE_WAVE_ASYMMETRIC_PWM_MODE3	Timer generates Asymmetric Triangle-wave PWM output. In PWM mode 3, the duty cycle does not need to be updated at each tough/crest interrupt. Instead, the trough and crest duty cycle values can be set once and only need to be updated when the application needs to change the duty cycle.

timer_direction_t

enum timer_direction_t

Direction of timer count

Enumerator
TIMER_DIRECTION_DOWN	Timer count goes up.
TIMER_DIRECTION_UP	Timer count goes down.

timer_source_div_t

enum timer_source_div_t

Clock source divisors

Enumerator
TIMER_SOURCE_DIV_1	Timer clock source divided by 1.
TIMER_SOURCE_DIV_2	Timer clock source divided by 2.
TIMER_SOURCE_DIV_4	Timer clock source divided by 4.
TIMER_SOURCE_DIV_8	Timer clock source divided by 8.
TIMER_SOURCE_DIV_16	Timer clock source divided by 16.
TIMER_SOURCE_DIV_32	Timer clock source divided by 32.
TIMER_SOURCE_DIV_64	Timer clock source divided by 64.
TIMER_SOURCE_DIV_128	Timer clock source divided by 128.
TIMER_SOURCE_DIV_256	Timer clock source divided by 256.
TIMER_SOURCE_DIV_512	Timer clock source divided by 512.
TIMER_SOURCE_DIV_1024	Timer clock source divided by 1024.
TIMER_SOURCE_DIV_2048	Timer clock source divided by 2048.
TIMER_SOURCE_DIV_4096	Timer clock source divided by 4096.
TIMER_SOURCE_DIV_8192	Timer clock source divided by 8912.
TIMER_SOURCE_DIV_16384	Timer clock source divided by 16384.
TIMER_SOURCE_DIV_32768	Timer clock source divided by 32768.
TIMER_SOURCE_DIV_1	Timer clock source divided by 1.
TIMER_SOURCE_DIV_2	Timer clock source divided by 2.
TIMER_SOURCE_DIV_4	Timer clock source divided by 4.
TIMER_SOURCE_DIV_8	Timer clock source divided by 8.
TIMER_SOURCE_DIV_16	Timer clock source divided by 16.
TIMER_SOURCE_DIV_32	Timer clock source divided by 32.
TIMER_SOURCE_DIV_64	Timer clock source divided by 64.
TIMER_SOURCE_DIV_128	Timer clock source divided by 128.
TIMER_SOURCE_DIV_256	Timer clock source divided by 256.
TIMER_SOURCE_DIV_512	Timer clock source divided by 512.
TIMER_SOURCE_DIV_1024	Timer clock source divided by 1024.
TIMER_SOURCE_DIV_2048	Timer clock source divided by 2048.
TIMER_SOURCE_DIV_4096	Timer clock source divided by 4096.
TIMER_SOURCE_DIV_8192	Timer clock source divided by 8912.
TIMER_SOURCE_DIV_16384	Timer clock source divided by 16384.
TIMER_SOURCE_DIV_32768	Timer clock source divided by 32768.
TIMER_SOURCE_DIV_1	Timer clock source divided by 1.
TIMER_SOURCE_DIV_2	Timer clock source divided by 2.
TIMER_SOURCE_DIV_4	Timer clock source divided by 4.
TIMER_SOURCE_DIV_8	Timer clock source divided by 8.
TIMER_SOURCE_DIV_16	Timer clock source divided by 16.
TIMER_SOURCE_DIV_32	Timer clock source divided by 32.
TIMER_SOURCE_DIV_64	Timer clock source divided by 64.
TIMER_SOURCE_DIV_128	Timer clock source divided by 128.
TIMER_SOURCE_DIV_256	Timer clock source divided by 256.
TIMER_SOURCE_DIV_512	Timer clock source divided by 512.
TIMER_SOURCE_DIV_1024	Timer clock source divided by 1024.
TIMER_SOURCE_DIV_8192	Timer clock source divided by 8192.