hardware_timer

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 microsecondsReturns the low 32 bits of the hardware timer. More...
 
uint64_t time_us_64 (void)
 Return the current 64 bit timestamp value in microsecondsReturns 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). 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_numThis method hard asserts if the hardware alarm is currently claimed. More...
 
int hardware_alarm_claim_unused (bool required)
 cooperatively claim the use of this hardware alarm_numThis method attempts to claim an unused hardware alarm 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 coreThis 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. More...
 
bool hardware_alarm_set_target (uint alarm_num, absolute_time_t t)
 Set the current target for the specified hardware alarmThis will replace any existing target. 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 alarmThis 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. 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:

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:

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

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_numthe 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_msdelay amount in milliseconds

◆ busy_wait_until()

void busy_wait_until ( absolute_time_t  t)

Busy wait wasting cycles until after the specified timestamp.

Parameters
tAbsolute 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_usdelay 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_usdelay 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_numthe hardware alarm number

◆ hardware_alarm_claim()

void hardware_alarm_claim ( uint  alarm_num)

cooperatively claim the use of this hardware alarm_numThis method hard asserts if the hardware alarm is currently claimed.

Parameters
alarm_numthe 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_numThis 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 alarmThis 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_numthe 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_numthe 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 coreThis 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_numthe hardware alarm number
callbackthe 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 alarmThis will replace any existing target.

Parameters
alarm_numthe hardware alarm number
tthe 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_numthe 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
tAbsolute 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 microsecondsReturns 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 ( void  )

Return the current 64 bit timestamp value in microsecondsReturns 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

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