Low-level hardware timer API.
More...
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>
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;
return 0;
}
return true;
}
int main() {
printf("Hello Timer!\n");
while (!timer_fired) {
}
printf("cancelled... %d\n", cancelled);
printf("cancelled... %d\n", cancelled);
printf("Done\n");
return 0;
}
static alarm_id_t add_alarm_in_ms(uint32_t ms, alarm_callback_t callback, void *user_data, bool fire_if_past)
Add an alarm callback to be called after a delay specified in milliseconds.
Definition: time.h:568
int32_t alarm_id_t
The identifier for an alarm.
Definition: time.h:336
uint64_t PICO_WEAK_FUNCTION_IMPL_NAME() time_us_64()
Return the current 64 bit timestamp value in microseconds.
Definition: timer.c:33
void stdio_init_all(void)
Initialize all of the present standard stdio types that are linked into the binary.
Definition: stdio.c:265
static bool add_repeating_timer_ms(int32_t delay_ms, repeating_timer_callback_t callback, void *user_data, repeating_timer_t *out)
Add a repeating timer that is called repeatedly at the specified interval in milliseconds.
Definition: time.h:698
bool cancel_repeating_timer(repeating_timer_t *timer)
Cancel a repeating timer.
Definition: time.c:322
void sleep_ms(uint32_t ms)
Wait for the given number of milliseconds before returning.
Definition: time.c:392
Information about a repeating timer.
Definition: time.h:609
- See also
- pico_time
◆ hardware_alarm_callback_t
typedef void(* hardware_alarm_callback_t) (uint alarm_num) |
◆ 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()
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
-
◆ 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_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()
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()
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()
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()
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.