Timers

The RP2350 has two 64 bit timers counting microseconds monotonically increasing. The timer registers should not be written from application code. With 64 bits and 1 MHz, they can count for more than half a billion years before wrapping around.

The timer can be used to set an alarm, which will trigger a callback function. The alarms match on the lower 32 bits of the 64-bit counter, which means they can be fired at a maximum of 2^32 microseconds into the future. This is equivalent to approximately 4295 seconds. As of 20250916, the Pico SDK by default supports configuration of 16 timer callbacks (see the PICO_TIME_DEFAULT_ALARM_POOL_MAX_TIMERS in time.h).

The alarm callback function must follow:

typedef int64_t (*alarm_callback_t)(alarm_id_t id, void *user_data);

And can be registered using the function

static inline alarm_id_t add_alarm_in_ms(uint32_t ms, alarm_callback_t callback, void *user_data, bool fire_if_past)
`` in time.h

The alarm can be configured to fire after a number of milliseconds or microseconds:
```c
    // configure for ms
    uint32_t alarmId = add_alarm_in_ms(1000, &my_alarm_callback, &user_data, fire_if_past); // 1000 ms

    // or configure for us
    uint32_t alarmId = add_alarm_in_us(2000, &my_alarm_callback, &user_data, fire_if_past); // 2000 us

    hard_assert(alarmId > 0); // if alarm id is negative, the configuration failed

The user_data provided will be passed to the alarm callback. It can be set to NULL if it is not used. fire_if_past is a boolean and if set to true and the alarm time falls before the alarm can be set, the callback will be called immediately.

The return value of the alarm callback function determines if and when the alarm will fire again.

int64_t my_alarm_callback(alarm_id_t id, void *user_data)
{
    uint64_t usSinceBoot = get_absolute_time();
    printf("Got callback from alarm id: %d - us since boot: %d\r\n", id, usSinceBoot);

    // return 0; // don't reschedule the alarm

    // return 1000*1000; // reschedule after 1.000.000 us from the time this method returns

    return -1000*1000; // reschedule after 1.000.000 us from the time the alarm was previously scheduled to fire
}

The Pico 2 SDK also has helper functions to create repeating timers, see e.g. add_repeating_timer_ms in time.h. An example can be found in the datasheet https://datasheets.raspberrypi.com/rp2350/rp2350-datasheet.pdf on page 1187.