hw_timer: Hardware Timers

Driver for hardware timers.

Variables

USE_US_TIMER

0 (default): Use default /256 prescale for Timer2 1: Use /16 prescale

The following functions depend on Timer2: - NOW() return value, the Timer2 tick count - Software timers - System time

Software timers are driven by Timer2, which by default uses a /256 prescale providing a resolution of 3.2us and a range of 1’ 54”.

Enabling this setting increases the resolution to 200ns but reduces the maximum software timer to 7” 9.5s.

API Documentation

enum hw_timer_clkdiv_t

Values:

enumerator TIMER_CLKDIV_1
enumerator TIMER_CLKDIV_16
enumerator TIMER_CLKDIV_256
enumerator TIMER_CLKDIV_1
enumerator TIMER_CLKDIV_16
enumerator TIMER_CLKDIV_256
enumerator TIMER_CLKDIV_1
enumerator TIMER_CLKDIV_16
enumerator TIMER_CLKDIV_256
enum hw_timer_intr_type_t

Values:

enumerator TIMER_EDGE_INT
enumerator TIMER_LEVEL_INT
enumerator TIMER_EDGE_INT
enumerator TIMER_LEVEL_INT
enumerator TIMER_EDGE_INT
enumerator TIMER_LEVEL_INT
enum hw_timer_source_type_t

Values:

enumerator TIMER_FRC1_SOURCE
enumerator TIMER_NMI_SOURCE
enumerator TIMER_FRC1_SOURCE
enumerator TIMER_NMI_SOURCE
enumerator TIMER_FRC1_SOURCE
enumerator TIMER_NMI_SOURCE
enum hw_timer_clkdiv_t

Values:

enumerator TIMER_CLKDIV_1
enumerator TIMER_CLKDIV_16
enumerator TIMER_CLKDIV_256
enumerator TIMER_CLKDIV_1
enumerator TIMER_CLKDIV_16
enumerator TIMER_CLKDIV_256
enumerator TIMER_CLKDIV_1
enumerator TIMER_CLKDIV_16
enumerator TIMER_CLKDIV_256
enum hw_timer_intr_type_t

Values:

enumerator TIMER_EDGE_INT
enumerator TIMER_LEVEL_INT
enumerator TIMER_EDGE_INT
enumerator TIMER_LEVEL_INT
enumerator TIMER_EDGE_INT
enumerator TIMER_LEVEL_INT
enum hw_timer_source_type_t

Values:

enumerator TIMER_FRC1_SOURCE
enumerator TIMER_NMI_SOURCE
enumerator TIMER_FRC1_SOURCE
enumerator TIMER_NMI_SOURCE
enumerator TIMER_FRC1_SOURCE
enumerator TIMER_NMI_SOURCE
enum hw_timer_clkdiv_t

Values:

enumerator TIMER_CLKDIV_1
enumerator TIMER_CLKDIV_16
enumerator TIMER_CLKDIV_256
enumerator TIMER_CLKDIV_1
enumerator TIMER_CLKDIV_16
enumerator TIMER_CLKDIV_256
enumerator TIMER_CLKDIV_1
enumerator TIMER_CLKDIV_16
enumerator TIMER_CLKDIV_256
enum hw_timer_intr_type_t

Values:

enumerator TIMER_EDGE_INT
enumerator TIMER_LEVEL_INT
enumerator TIMER_EDGE_INT
enumerator TIMER_LEVEL_INT
enumerator TIMER_EDGE_INT
enumerator TIMER_LEVEL_INT
enum hw_timer_source_type_t

Values:

enumerator TIMER_FRC1_SOURCE
enumerator TIMER_NMI_SOURCE
enumerator TIMER_FRC1_SOURCE
enumerator TIMER_NMI_SOURCE
enumerator TIMER_FRC1_SOURCE
enumerator TIMER_NMI_SOURCE
typedef void (*hw_timer_callback_t)(void *arg)
typedef void (*hw_timer_callback_t)(void *arg)
typedef void (*hw_timer_callback_t)(void *arg)
struct hw_timer_private_t hw_timer_private
void hw_timer1_attach_interrupt(hw_timer_source_type_t source_type, hw_timer_callback_t callback, void *arg)

Attach an interrupt for the timer.

Parameters:

  • source_type – Ignored, uses APB clock source

  • callback – Callback function invoked via timer interrupt

  • arg – Passed to callback function

  • source_type –

  • callback – Callback function invoked via timer interrupt

  • arg – Passed to callback function

inline void hw_timer1_enable(hw_timer_clkdiv_t div, hw_timer_intr_type_t intr_type, bool auto_load)

Enable the timer.

Note: With one-shot timer application callback must stop the timer when it is no longer required. This is to reduce callback latency. If this is not done, timer will trigger again when timer counter wraps around to 0. For /16 divisor this is only 1.7s.

Parameters:

  • div –

  • intr_type – Ignored, always level-triggered

  • auto_load –

  • div –

  • intr_type –

  • auto_load – true for repeating timer, false for one-shot

  • div –

  • intr_type –

  • auto_load –

void hw_timer1_write(uint32_t ticks)

Set the timer interval.

Set the timer interval and arm.

Parameters:

ticks –

void hw_timer1_disable(void)

Disable the timer.

void hw_timer1_detach_interrupt(void)

Detach interrupt from the timer.

uint32_t hw_timer1_read(void)

Get timer1 count.

Return values:

uint32_t – Current count value, counts from initial value down to 0

static uint32_t hw_timer2_read(void)

Read current timer2 value.

Return values:

uint32_t –

void hw_timer_init(void)

Initialise hardware timers.

Note

Called by startup code

void hw_timer2_set_alarm(uint32_t ticks)

Set timer2 alarm count value.

Note

For internal use ONLY; used by software timers

Parameters:

ticks –

uint32_t hw_timer_ticks()

Fetch 32-bit microsecond count.

All timers reference from a single 64-bit counter. We use only the lower 32 bits here as it provides lowest latency and compatibility with existing API.

HW_TIMER1_GROUP
HW_TIMER1_INDEX
MAX_HW_TIMER1_INTERVAL

Maximum timer interval in ticks.

Note

The corresponding time interval depends on the prescaler in use: 

    /1 - 26.84s
    /16 - 429.50s
    /256 - 6871.95s
ESP32 supports a wide range of prescalers and uses 54-bit counter value. Limiting the range 31 bits avoids issues with overflows and moving to 64-bit calculations.

MIN_HW_TIMER1_INTERVAL_US

Minimum hardware interval in microseconds.

Note

Attempting to use repetitive interrupts below this level can lead to system instabliity and lockups, due to the software overhead in servicing the interrupts.

NOW()
MAX_HW_TIMER1_INTERVAL

Maximum timer interval in ticks.

Note

The corresponding time interval depends on the prescaler in use: 

    /1 - 0.1048s
    /16 - 1.677s
    /256 - 26.84s

MIN_HW_TIMER1_INTERVAL_US

Minimum hardware interval in microseconds.

Note

Attempting to use repetitive interrupts below this level can lead to system instabliity and lockups, due to the software overhead in servicing the interrupts.

HW_TIMER2_CLKDIV
HW_TIMER2_CLK
MAX_HW_TIMER1_INTERVAL

Maximum timer interval in ticks.

MIN_HW_TIMER1_INTERVAL_US

Minimum hardware interval in microseconds.

Note

Attempting to use repetitive interrupts below this level can lead to system instabliity and lockups, due to the software overhead in servicing the interrupts.

HW_TIMER2_CLK
struct hw_timer_private_t
#include <hw_timer.h>