RA Flexible Software Package Documentation  Release v4.1.0

 
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.

Implemented by:

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_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(* 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_api_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.

Implemented as
Parameters
[in]p_ctrlPointer to control block. Must be declared by user. Elements set here.
[in]p_cfgPointer 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.

Implemented as
Parameters
[in]p_ctrlControl 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.

Implemented as
Parameters
[in]p_ctrlControl 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.

Implemented as
Parameters
[in]p_ctrlControl 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.

Implemented as
Parameters
[in]p_ctrlControl 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.

Implemented as
Parameters
[in]p_ctrlControl 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.

Implemented as
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_ctrlControl block set in timer_api_t::open call for this timer.
[in]p_periodTime 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.

Implemented as
Parameters
[in]p_ctrlControl block set in timer_api_t::open call for this timer.
[in]duty_cycle_countsTime until duty cycle should expire.
[in]pinWhich output pin to update. See implementation for details.

◆ 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.

Implemented as
Parameters
[in]p_ctrlControl block set in timer_api_t::open call for this timer.
[out]p_infoCollection 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.

Implemented as
Parameters
[in]p_ctrlControl block set in timer_api_t::open call for this timer.
[out]p_statusCurrent status of this timer.

◆ callbackSet

fsp_err_t(* timer_api_t::callbackSet) (timer_ctrl_t *const p_api_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.

Implemented as
Parameters
[in]p_ctrlControl block set in timer_api_t::open call for this timer.
[in]p_callbackCallback function to register
[in]p_contextPointer to send to callback function
[in]p_working_memoryPointer 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.

Implemented as
Parameters
[in]p_ctrlControl 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.

Implemented as

Enumeration Type Documentation

◆ 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_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_variant_t

Timer variant types.

Enumerator
TIMER_VARIANT_32_BIT 

32-bit timer

TIMER_VARIANT_16_BIT 

16-bit timer

◆ 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_mode_t

Timer operational modes

Enumerator
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

Direction of timer count

Enumerator
TIMER_DIRECTION_DOWN 

Timer count goes up.

TIMER_DIRECTION_UP 

Timer count goes down.

◆ timer_source_div_t

PCLK 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.