hardware_timer

Low-level hardware timer API. More...

Typedefs
typedef void(*	hardware_alarm_callback_t) (uint alarm_num)

Functions
static uint32_t	time_us_32 (void)
	Return a 32 bit timestamp value in microseconds. More...
uint64_t	time_us_64 (void)
	Return the current 64 bit timestamp value in microseconds. More...
void	busy_wait_us_32 (uint32_t delay_us)
	Busy wait wasting cycles for the given (32 bit) number of microseconds. More...
void	busy_wait_us (uint64_t delay_us)
	Busy wait wasting cycles for the given (64 bit) number of microseconds. More...
void	busy_wait_ms (uint32_t delay_ms)
	Busy wait wasting cycles for the given number of milliseconds. More...
void	busy_wait_until (absolute_time_t t)
	Busy wait wasting cycles until after the specified timestamp. More...
static bool	time_reached (absolute_time_t t)
	Check if the specified timestamp has been reached. More...
void	hardware_alarm_claim (uint alarm_num)
	cooperatively claim the use of this hardware alarm_num More...
int	hardware_alarm_claim_unused (bool required)
	cooperatively claim the use of this hardware alarm_num More...
void	hardware_alarm_unclaim (uint alarm_num)
	cooperatively release the claim on use of this hardware alarm_num More...
bool	hardware_alarm_is_claimed (uint alarm_num)
	Determine if a hardware alarm has been claimed. More...
void	hardware_alarm_set_callback (uint alarm_num, hardware_alarm_callback_t callback)
	Enable/Disable a callback for a hardware timer on this core. More...
bool	hardware_alarm_set_target (uint alarm_num, absolute_time_t t)
	Set the current target for the specified hardware alarm. More...
void	hardware_alarm_cancel (uint alarm_num)
	Cancel an existing target (if any) for a given hardware_alarm. More...
void	hardware_alarm_force_irq (uint alarm_num)
	Force and IRQ for a specific hardware alarm. More...

Detailed Description

Low-level hardware timer API.

This API provides medium level access to the timer HW. See also pico_time which provides higher levels functionality using the hardware timer.

The timer peripheral on RP2040 supports the following features:

• single 64-bit counter, incrementing once per microsecond
• Latching two-stage read of counter, for race-free read over 32 bit bus
• Four alarms: match on the lower 32 bits of counter, IRQ on match.

By default the timer uses a one microsecond reference that is generated in the Watchdog (see Section 4.8.2) which is derived from the clk_ref.

The timer has 4 alarms, and can output a separate interrupt for each alarm. The alarms match on the lower 32 bits of the 64 bit counter which means they can be fired a maximum of 2^32 microseconds into the future. This is equivalent to:

• 2^32 ÷ 10^6: ~4295 seconds
• 4295 ÷ 60: ~72 minutes

The timer is expected to be used for short sleeps, if you want a longer alarm see the hardware_rtc functions.

Example

 
#include <stdio.h>
#include "pico/stdlib.h"
 
volatile bool timer_fired = false;
 
int64_t alarm_callback(alarm_id_t id, void *user_data) {
    printf("Timer %d fired!\n", (int) id);
    timer_fired = true;
    // Can return a value here in us to fire in the future
    return 0;
}
 
bool repeating_timer_callback(struct repeating_timer *t) {
    printf("Repeat at %lld\n", time_us_64());
    return true;
}
 
int main() {
    stdio_init_all();
    printf("Hello Timer!\n");
 
    // Call alarm_callback in 2 seconds
    add_alarm_in_ms(2000, alarm_callback, NULL, false);
 
    // Wait for alarm callback to set timer_fired
    while (!timer_fired) {
        tight_loop_contents();
    }
 
    // Create a repeating timer that calls repeating_timer_callback.
    // If the delay is > 0 then this is the delay between the previous callback ending and the next starting.
    // If the delay is negative (see below) then the next call to the callback will be exactly 500ms after the
    // start of the call to the last callback
    struct repeating_timer timer;
    add_repeating_timer_ms(500, repeating_timer_callback, NULL, &timer);
    sleep_ms(3000);
    bool cancelled = cancel_repeating_timer(&timer);
    printf("cancelled... %d\n", cancelled);
    sleep_ms(2000);
 
    // Negative delay so means we will call repeating_timer_callback, and call it again
    // 500ms later regardless of how long the callback took to execute
    add_repeating_timer_ms(-500, repeating_timer_callback, NULL, &timer);
    sleep_ms(3000);
    cancelled = cancel_repeating_timer(&timer);
    printf("cancelled... %d\n", cancelled);
    sleep_ms(2000);
    printf("Done\n");
    return 0;
}

See also

pico_time

Typedef Documentation

hardware_alarm_callback_t

typedef void(* hardware_alarm_callback_t) (uint alarm_num)

Callback function type for hardware alarms

Parameters

alarm_num

the hardware alarm number

See also

hardware_alarm_set_callback()

Function Documentation

busy_wait_ms()

void busy_wait_ms

(

uint32_t

delay_ms

)

Busy wait wasting cycles for the given number of milliseconds.

Parameters

delay_ms

delay amount in milliseconds

busy_wait_until()

void busy_wait_until

(

absolute_time_t

t

)

Busy wait wasting cycles until after the specified timestamp.

Parameters

t	Absolute time to wait until

busy_wait_us()

void busy_wait_us

(

uint64_t

delay_us

)

Busy wait wasting cycles for the given (64 bit) number of microseconds.

Parameters

delay_us

delay amount in microseconds

busy_wait_us_32()

void busy_wait_us_32

(

uint32_t

delay_us

)

Busy wait wasting cycles for the given (32 bit) number of microseconds.

Parameters

delay_us

delay amount in microseconds

Busy wait wasting cycles for the given (32 bit) number of microseconds.

hardware_alarm_cancel()

void hardware_alarm_cancel

(

uint

alarm_num

)

Cancel an existing target (if any) for a given hardware_alarm.

Parameters

alarm_num

the hardware alarm number

hardware_alarm_claim()

void hardware_alarm_claim

(

uint

alarm_num

)

cooperatively claim the use of this hardware alarm_num

This method hard asserts if the hardware alarm is currently claimed.

Parameters

alarm_num

the hardware alarm to claim

See also

hardware_claiming

hardware_alarm_claim_unused()

int hardware_alarm_claim_unused

(

bool

required

)

cooperatively claim the use of this hardware alarm_num

This method attempts to claim an unused hardware alarm

Returns

alarm_num the hardware alarm claimed or -1 if requires was false, and none are available

See also

hardware_claiming

hardware_alarm_force_irq()

void hardware_alarm_force_irq

(

uint

alarm_num

)

Force and IRQ for a specific hardware alarm.

This method will forcibly make sure the current alarm callback (if present) for the hardware alarm is called from an IRQ context after this call. If an actual callback is due at the same time then the callback may only be called once.

Calling this method does not otherwise interfere with regular callback operations.

Parameters

alarm_num

the hardware alarm number

hardware_alarm_is_claimed()

bool hardware_alarm_is_claimed

(

uint

alarm_num

)

Determine if a hardware alarm has been claimed.

Parameters

alarm_num

the hardware alarm number

Returns

true if claimed, false otherwise

See also

hardware_alarm_claim

hardware_alarm_set_callback()

void hardware_alarm_set_callback	(	uint	alarm_num,
		hardware_alarm_callback_t	callback
	)

Enable/Disable a callback for a hardware timer on this core.

This method enables/disables the alarm IRQ for the specified hardware alarm on the calling core, and set the specified callback to be associated with that alarm.

This callback will be used for the timeout set via hardware_alarm_set_target

Note

This will install the handler on the current core if the IRQ handler isn't already set. Therefore the user has the opportunity to call this up from the core of their choice

Parameters

alarm_num	the hardware alarm number
callback	the callback to install, or NULL to unset

See also

hardware_alarm_set_target()

hardware_alarm_set_target()

bool hardware_alarm_set_target	(	uint	alarm_num,
		absolute_time_t	t
	)

Set the current target for the specified hardware alarm.

This will replace any existing target

Parameters

alarm_num	the hardware alarm number
t	the target timestamp

Returns

true if the target was "missed"; i.e. it was in the past, or occurred before a future hardware timeout could be set

hardware_alarm_unclaim()

void hardware_alarm_unclaim

(

uint

alarm_num

)

cooperatively release the claim on use of this hardware alarm_num

Parameters

alarm_num

the hardware alarm to unclaim

See also

hardware_claiming

time_reached()

static bool time_reached ( absolute_time_t  t )

inlinestatic

Check if the specified timestamp has been reached.

Parameters

t	Absolute time to compare against current time

Returns

true if it is now after the specified timestamp

time_us_32()

static uint32_t time_us_32 ( void  )

inlinestatic

Return a 32 bit timestamp value in microseconds.

Returns the low 32 bits of the hardware timer.

Note

This value wraps roughly every 1 hour 11 minutes and 35 seconds.

Returns

the 32 bit timestamp

time_us_64()

uint64_t time_us_64

(

)

Return the current 64 bit timestamp value in microseconds.

Returns the full 64 bits of the hardware timer. The pico_time and other functions rely on the fact that this value monotonically increases from power up. As such it is expected that this value counts upwards and never wraps (we apologize for introducing a potential year 5851444 bug).

Returns

the 64 bit timestamp

Return the current 64 bit timestamp value in microseconds.