@web-font-path: "roboto-debian.css";
v2.2.0 (RP2040)
Loading...
Searching...
No Matches
hardware_timer

Low-level hardware timer API. More...

## Macros

#define | TIMER_ALARM_IRQ_NUM(timer, alarm_num)
| Returns the irq_num_t for the alarm interrupt from the given alarm on the given timer instance.
#define | TIMER_ALARM_NUM_FROM_IRQ(irq_num)
| Returns the alarm number from an irq_num_t. See TIMER_INSTANCE_NUM_FROM_IRQ to get the timer instance number.
#define | TIMER_NUM_FROM_IRQ(irq_num)
| Returns the alarm number from an irq_num_t. See TIMER_INSTANCE_NUM_FROM_IRQ to get the alarm number.
#define | PICO_DEFAULT_TIMER 0
| The default timer instance number of the timer instance used for APIs that don't take an explicit timer instance On RP2040 this must be 0 as there is only one timer instance .
#define | PICO_DEFAULT_TIMER_INSTANCE()
| Returns the default timer instance on the platform based on the setting of PICO_DEFAULT_TIMER.

## Typedefs

typedef void(* | hardware_alarm_callback_t) (uint alarm_num)

## Functions

static uint32_t | timer_time_us_32 (timer_hw_t *timer)
| Return a 32 bit timestamp value in microseconds for a given timer instance.
static uint32_t | time_us_32 (void)
| Return a 32 bit timestamp value in microseconds for the default timer instance.
uint64_t | timer_time_us_64 (timer_hw_t *timer)
| Return the current 64 bit timestamp value in microseconds for a given timer instance.
uint64_t | time_us_64 (void)
| Return the current 64 bit timestamp value in microseconds for the default timer instance.
void | timer_busy_wait_us_32 (timer_hw_t *timer, uint32_t delay_us)
| Busy wait wasting cycles for the given (32 bit) number of microseconds using the given timer instance.
void | busy_wait_us_32 (uint32_t delay_us)
| Busy wait wasting cycles for the given (32 bit) number of microseconds using the default timer instance.
void | timer_busy_wait_us (timer_hw_t *timer, uint64_t delay_us)
| Busy wait wasting cycles for the given (64 bit) number of microseconds using the given timer instance.
void | busy_wait_us (uint64_t delay_us)
| Busy wait wasting cycles for the given (64 bit) number of microseconds using the default timer instance.
void | timer_busy_wait_ms (timer_hw_t *timer, uint32_t delay_ms)
| Busy wait wasting cycles for the given number of milliseconds using the given timer instance.
void | busy_wait_ms (uint32_t delay_ms)
| Busy wait wasting cycles for the given number of milliseconds using the default timer instance.
void | timer_busy_wait_until (timer_hw_t *timer, absolute_time_t t)
| Busy wait wasting cycles until after the specified timestamp using the given timer instance.
void | busy_wait_until (absolute_time_t t)
| Busy wait wasting cycles until after the specified timestamp using the default timer instance.
static bool | timer_time_reached (timer_hw_t *timer, absolute_time_t t)
| Check if the specified timestamp has been reached on the given timer instance.
static bool | time_reached (absolute_time_t t)
| Check if the specified timestamp has been reached on the default timer instance.
void | timer_hardware_alarm_claim (timer_hw_t *timer, uint alarm_num)
| cooperatively claim the use of this hardware alarm_num on the given timer instance
void | hardware_alarm_claim (uint alarm_num)
| cooperatively claim the use of this hardware alarm_num on the default timer instance
int | timer_hardware_alarm_claim_unused (timer_hw_t *timer, bool required)
| cooperatively claim the use of a hardware alarm_num on the given timer instance
int | hardware_alarm_claim_unused (bool required)
| cooperatively claim the use of a hardware alarm_num on the default timer instance
void | timer_hardware_alarm_unclaim (timer_hw_t *timer, uint alarm_num)
| cooperatively release the claim on use of this hardware alarm_num on the given timer instance
void | hardware_alarm_unclaim (uint alarm_num)
| cooperatively release the claim on use of this hardware alarm_num on the default timer instance
bool | timer_hardware_alarm_is_claimed (timer_hw_t *timer, uint alarm_num)
| Determine if a hardware alarm has been claimed on the given timer instance.
bool | hardware_alarm_is_claimed (uint alarm_num)
| Determine if a hardware alarm has been claimed on the default timer instance.
void | timer_hardware_alarm_set_callback (timer_hw_t *timer, uint alarm_num, hardware_alarm_callback_t callback)
| Enable/Disable a callback for a hardware alarm for a given timer instance on this core.
void | hardware_alarm_set_callback (uint alarm_num, hardware_alarm_callback_t callback)
| Enable/Disable a callback for a hardware alarm on the default timer instance on this core.
bool | timer_hardware_alarm_set_target (timer_hw_t *timer, uint alarm_num, absolute_time_t t)
| Set the current target for a specific hardware alarm on the given timer instance.
bool | hardware_alarm_set_target (uint alarm_num, absolute_time_t t)
| Set the current target for the specified hardware alarm on the default timer instance.
void | timer_hardware_alarm_cancel (timer_hw_t *timer, uint alarm_num)
| Cancel an existing target (if any) for a specific hardware_alarm on the given timer instance.
void | hardware_alarm_cancel (uint alarm_num)
| Cancel an existing target (if any) for the specified hardware_alarm on the default timer instance.
void | timer_hardware_alarm_force_irq (timer_hw_t *timer, uint alarm_num)
| Force and IRQ for a specific hardware alarm on the given timer instance.
void | hardware_alarm_force_irq (uint alarm_num)
| Force and IRQ for a specific hardware alarm on the default timer instance.
static uint | timer_hardware_alarm_get_irq_num (timer_hw_t *timer, uint alarm_num)
| Returns the irq_num_t for the alarm interrupt from the given alarm on the given timer instance.
static uint | hardware_alarm_get_irq_num (uint alarm_num)
| Returns the irq_num_t for the alarm interrupt from the given alarm on the default timer instance.
static uint | timer_get_index (timer_hw_t *timer)
| Returns the timer number for a timer instance.
static timer_hw_t * | timer_get_instance (uint timer_num)
| Returns the timer instance with the given timer number.

## 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 RP-series microcontrollers supports the following features:

- RP2040 single 64-bit counter, incrementing once per microsecond
- RP2350 two 64-bit counters, ticks generated from the tick block
- 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.

On RP2040, by default the timer uses a one microsecond reference that is generated in the Watchdog (see RP2040 Datasheet 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

See also
  pico_time

## Macro Definition Documentation

## PICO_DEFAULT_TIMER_INSTANCE

#define PICO_DEFAULT_TIMER_INSTANCE | ( |  | ) |

Returns the default timer instance on the platform based on the setting of PICO_DEFAULT_TIMER.

Note this macro is intended to resolve at compile time, and does no parameter checking

## TIMER_ALARM_IRQ_NUM

#define TIMER_ALARM_IRQ_NUM | ( |  | timer,
|  |  | alarm_num )

Returns the irq_num_t for the alarm interrupt from the given alarm on the given timer instance.

Note this macro is intended to resolve at compile time, and does no parameter checking

## TIMER_ALARM_NUM_FROM_IRQ

#define TIMER_ALARM_NUM_FROM_IRQ | ( |  | irq_num | ) |

Returns the alarm number from an irq_num_t. See TIMER_INSTANCE_NUM_FROM_IRQ to get the timer instance number.

Note this macro is intended to resolve at compile time, and does no parameter checking

## TIMER_NUM_FROM_IRQ

#define TIMER_NUM_FROM_IRQ | ( |  | irq_num | ) |

Returns the alarm number from an irq_num_t. See TIMER_INSTANCE_NUM_FROM_IRQ to get the alarm number.

Note this macro is intended to resolve at compile time, and does no parameter checking

## 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 using the default timer instance.

Parameters

  delay_ms | delay amount in milliseconds

See also
  timer_busy_wait_ms

## busy_wait_until()

void busy_wait_until | ( | absolute_time_t | t | ) |

Busy wait wasting cycles until after the specified timestamp using the default timer instance.

Parameters

  t | Absolute time to wait until

See also
  timer_busy_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 using the default timer instance.

Parameters

  delay_us | delay amount in microseconds

See also
  timer_busy_wait_us

## 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 using the default timer instance.

Parameters

  delay_us | delay amount in microseconds

See also
  timer_busy_wait_us_32

## hardware_alarm_cancel()

void hardware_alarm_cancel | ( | uint | alarm_num | ) |

Cancel an existing target (if any) for the specified hardware_alarm on the default timer instance.

Parameters

  alarm_num | the hardware alarm number

See also
  timer_hardware_alarm_cancel

## hardware_alarm_claim()

void hardware_alarm_claim | ( | uint | alarm_num | ) |

cooperatively claim the use of this hardware alarm_num on the default timer instance

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

Parameters

  alarm_num | the hardware alarm to claim

See also
  timer_hardware_alarm_claim
  hardware_claim

## hardware_alarm_claim_unused()

int hardware_alarm_claim_unused | ( | bool | required | ) |

cooperatively claim the use of a hardware alarm_num on the default timer instance

This method attempts to claim an unused hardware alarm

Parameters

  required | if true the function will panic if none are available

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

See also
  timer_hardware_alarm_claim_unused
  hardware_claim

## hardware_alarm_force_irq()

void hardware_alarm_force_irq | ( | uint | alarm_num | ) |

Force and IRQ for a specific hardware alarm on the default timer instance.

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

See also
  timer_hardware_alarm_force_irq

## hardware_alarm_get_irq_num()

uint hardware_alarm_get_irq_num | ( | uint | alarm_num | ) |

inline static

Returns the irq_num_t for the alarm interrupt from the given alarm on the default timer instance.

Parameters

  alarm_num | the alarm number

## hardware_alarm_is_claimed()

bool hardware_alarm_is_claimed | ( | uint | alarm_num | ) |

Determine if a hardware alarm has been claimed on the default timer instance.

Parameters

  alarm_num | the hardware alarm number

Returns
  true if claimed, false otherwise

See also
  timer_hardware_alarm_is_claimed
  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 alarm on the default timer instance 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
  timer_hardware_alarm_set_callback
  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 on the default timer instance.

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

See also
  timer_hardware_alarm_set_target

## hardware_alarm_unclaim()

void hardware_alarm_unclaim | ( | uint | alarm_num | ) |

cooperatively release the claim on use of this hardware alarm_num on the default timer instance

Parameters

  alarm_num | the hardware alarm to unclaim

See also
  timer_hardware_alarm_unclaim
  hardware_claim

## time_reached()

bool time_reached | ( | absolute_time_t | t | ) |

inline static

Check if the specified timestamp has been reached on the default timer instance.

Parameters

  t | Absolute time to compare against current time

Returns
  true if it is now after the specified timestamp

See also
  timer_time_reached

## time_us_32()

uint32_t time_us_32 | ( | void |  | ) |

inline static

Return a 32 bit timestamp value in microseconds for the default timer instance.

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

See also
  timer_time_us_32

## time_us_64()

uint64_t time_us_64 | ( | void |  | ) |

Return the current 64 bit timestamp value in microseconds for the default timer instance.

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

See also
  timer_time_us_64

## timer_busy_wait_ms()

void timer_busy_wait_ms | ( | timer_hw_t * | timer,
|  | uint32_t | delay_ms )

Busy wait wasting cycles for the given number of milliseconds using the given timer instance.

Parameters

  timer | the timer instance
  delay_ms | delay amount in milliseconds

See also
  busy_wait_ms

## timer_busy_wait_until()

void timer_busy_wait_until | ( | timer_hw_t * | timer,
|  | absolute_time_t | t )

Busy wait wasting cycles until after the specified timestamp using the given timer instance.

Parameters

  timer | the timer instance
  t | Absolute time to wait until

See also
  busy_wait_until

## timer_busy_wait_us()

void timer_busy_wait_us | ( | timer_hw_t * | timer,
|  | uint64_t | delay_us )

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

Parameters

  timer | the timer instance
  delay_us | delay amount in microseconds

See also
  busy_wait_us

## timer_busy_wait_us_32()

void timer_busy_wait_us_32 | ( | timer_hw_t * | timer,
|  | uint32_t | delay_us )

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

Parameters

  timer | the timer instance
  delay_us | delay amount in microseconds

See also
  busy_wait_us_32

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

## timer_get_index()

uint timer_get_index | ( | timer_hw_t * | timer | ) |

inline static

Returns the timer number for a timer instance.

Parameters

  timer | the timer instance

Returns
  the timer number

See also
  TIMER_NUM

## timer_get_instance()

timer_hw_t * timer_get_instance | ( | uint | timer_num | ) |

inline static

Returns the timer instance with the given timer number.

Parameters

  timer_num | the timer number

Returns
  the timer instance

## timer_hardware_alarm_cancel()

void timer_hardware_alarm_cancel | ( | timer_hw_t * | timer,
|  | uint | alarm_num )

Cancel an existing target (if any) for a specific hardware_alarm on the given timer instance.

Parameters

  timer | the timer instance
  alarm_num | the hardware alarm number

See also
  hardware_alarm_cancel

## timer_hardware_alarm_claim()

void timer_hardware_alarm_claim | ( | timer_hw_t * | timer,
|  | uint | alarm_num )

cooperatively claim the use of this hardware alarm_num on the given timer instance

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

Parameters

  timer | the timer instance
  alarm_num | the hardware alarm to claim

See also
  hardware_alarm_claim
  hardware_claim

## timer_hardware_alarm_claim_unused()

int timer_hardware_alarm_claim_unused | ( | timer_hw_t * | timer,
|  | bool | required )

cooperatively claim the use of a hardware alarm_num on the given timer instance

This method attempts to claim an unused hardware alarm

Parameters

  timer | the timer instance
  required | if true the function will panic if none are available

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

See also
  hardware_alarm_claim_unused
  hardware_claim

## timer_hardware_alarm_force_irq()

void timer_hardware_alarm_force_irq | ( | timer_hw_t * | timer,
|  | uint | alarm_num )

Force and IRQ for a specific hardware alarm on the given timer instance.

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

  timer | the timer instance
  alarm_num | the hardware alarm number

See also
  hardware_alarm_force_irq

## timer_hardware_alarm_get_irq_num()

uint timer_hardware_alarm_get_irq_num | ( | timer_hw_t * | timer,
|  | uint | alarm_num )

inline static

Returns the irq_num_t for the alarm interrupt from the given alarm on the given timer instance.

Parameters

  timer | the timer instance
  alarm_num | the alarm number

See also
  TIMER_ALARM_IRQ_NUM

## timer_hardware_alarm_is_claimed()

bool timer_hardware_alarm_is_claimed | ( | timer_hw_t * | timer,
|  | uint | alarm_num )

Determine if a hardware alarm has been claimed on the given timer instance.

Parameters

  timer | the timer instance
  alarm_num | the hardware alarm number

Returns
  true if claimed, false otherwise

See also
  hardware_alarm_is_claimed
  hardware_alarm_claim

## timer_hardware_alarm_set_callback()

void timer_hardware_alarm_set_callback | ( | timer_hw_t * | timer,
|  | uint | alarm_num,
|  | hardware_alarm_callback_t | callback )

Enable/Disable a callback for a hardware alarm for a given timer instance 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

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

See also
  hardware_alarm_set_callback
  timer_hardware_alarm_set_target()

## timer_hardware_alarm_set_target()

bool timer_hardware_alarm_set_target | ( | timer_hw_t * | timer,
|  | uint | alarm_num,
|  | absolute_time_t | t )

Set the current target for a specific hardware alarm on the given timer instance.

This will replace any existing target

Parameters

  timer | the timer instance
  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

See also
  hardware_alarm_set_target

## timer_hardware_alarm_unclaim()

void timer_hardware_alarm_unclaim | ( | timer_hw_t * | timer,
|  | uint | alarm_num )

cooperatively release the claim on use of this hardware alarm_num on the given timer instance

Parameters

  timer | the timer instance
  alarm_num | the hardware alarm to unclaim

See also
  hardware_alarm_unclaim
  hardware_claim

## timer_time_reached()

bool timer_time_reached | ( | timer_hw_t * | timer,
|  | absolute_time_t | t )

inline static

Check if the specified timestamp has been reached on the given timer instance.

Parameters

  timer | the timer instance
  t | Absolute time to compare against current time

Returns
  true if it is now after the specified timestamp

See also
  time_reached

## timer_time_us_32()

uint32_t timer_time_us_32 | ( | timer_hw_t * | timer | ) |

inline static

Return a 32 bit timestamp value in microseconds for a given timer instance.

Returns the low 32 bits of the hardware timer.

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

Parameters

  timer | the timer instance

Returns
  the 32 bit timestamp

See also
  time_us_32

## timer_time_us_64()

uint64_t timer_time_us_64 | ( | timer_hw_t * | timer | ) |

Return the current 64 bit timestamp value in microseconds for a given timer instance.

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

Parameters

  timer | the timer instance

Returns
  the 64 bit timestamp

See also
  time_us_64

Return the current 64 bit timestamp value in microseconds for a given timer instance.