@web-font-path: "roboto-debian.css";
Loading...
Searching...
No Matches
time.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6
7#ifndef _PICO_TIME_H
8#define _PICO_TIME_H
9
10#include "pico.h"
11#include "hardware/timer.h"
12
13#ifdef __cplusplus
14extern "C" {
15#endif
16
32// PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_TIME, Enable/disable assertions in the time module, type=bool, default=0, group=pico_time
33#ifndef PARAM_ASSERTIONS_ENABLED_TIME
34#define PARAM_ASSERTIONS_ENABLED_TIME 0
35#endif
36
37// PICO_CONFIG: PICO_TIME_SLEEP_OVERHEAD_ADJUST_US, How many microseconds to wake up early (and then busy_wait) to account for timer overhead when sleeping in low power mode, type=int, default=6, group=pico_time
38#ifndef PICO_TIME_SLEEP_OVERHEAD_ADJUST_US
39#define PICO_TIME_SLEEP_OVERHEAD_ADJUST_US 6
40#endif
64 return t;
65}
66
67static inline uint32_t us_to_ms(uint64_t us) {
68 if (us >> 32u) {
69 return (uint32_t)(us / 1000u);
70 } else {
71 return ((uint32_t)us) / 1000u;
72 }
73}
74
82static inline uint32_t to_ms_since_boot(absolute_time_t t) {
83 uint64_t us = to_us_since_boot(t);
84 return us_to_ms(us);
85}
86
94static inline absolute_time_t delayed_by_us(const absolute_time_t t, uint64_t us) {
96 uint64_t base = to_us_since_boot(t);
97 uint64_t delayed = base + us;
98 if ((int64_t)delayed < 0) {
99 // absolute_time_t (to allow for signed time deltas) is never greater than INT64_MAX which == at_the_end_of_time
100 delayed = INT64_MAX;
101 }
102 update_us_since_boot(&t2, delayed);
103 return t2;
104}
105
113static inline absolute_time_t delayed_by_ms(const absolute_time_t t, uint32_t ms) {
115 uint64_t base = to_us_since_boot(t);
116 uint64_t delayed = base + ms * 1000ull;
117 if ((int64_t)delayed < 0) {
118 // absolute_time_t (to allow for signed time deltas) is never greater than INT64_MAX which == at_the_end_of_time
119 delayed = INT64_MAX;
120 }
121 update_us_since_boot(&t2, delayed);
122 return t2;
123}
124
131static inline absolute_time_t make_timeout_time_us(uint64_t us) {
132 return delayed_by_us(get_absolute_time(), us);
133}
134
141static inline absolute_time_t make_timeout_time_ms(uint32_t ms) {
142 return delayed_by_ms(get_absolute_time(), ms);
143}
144
157 return (int64_t)(to_us_since_boot(to) - to_us_since_boot(from));
158}
159
170
177
187
191extern const absolute_time_t nil_time;
192
199static inline bool is_nil_time(absolute_time_t t) {
200 return !to_us_since_boot(t);
201}
202
232void sleep_until(absolute_time_t target);
233
242void sleep_us(uint64_t us);
243
251void sleep_ms(uint32_t ms);
252
286bool best_effort_wfe_or_timeout(absolute_time_t timeout_timestamp);
287
306// PICO_CONFIG: PICO_TIME_DEFAULT_ALARM_POOL_DISABLED, Disable the default alarm pool, type=bool, default=0, advanced=true, group=pico_time
307#ifndef PICO_TIME_DEFAULT_ALARM_POOL_DISABLED
320#define PICO_TIME_DEFAULT_ALARM_POOL_DISABLED 0
321#endif
322
323// PICO_CONFIG: PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM, Select which HW alarm is used for the default alarm pool, min=0, max=3, default=3, advanced=true, group=pico_time
324#ifndef PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM
330#define PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM 3
331#endif
332
333// PICO_CONFIG: PICO_TIME_DEFAULT_ALARM_POOL_MAX_TIMERS, Selects the maximum number of concurrent timers in the default alarm pool, min=0, max=255, default=16, advanced=true, group=pico_time
334#ifndef PICO_TIME_DEFAULT_ALARM_POOL_MAX_TIMERS
343#define PICO_TIME_DEFAULT_ALARM_POOL_MAX_TIMERS 16
344#endif
345
359typedef int32_t alarm_id_t; // note this is signed because we use -1 as a meaningful error value
360
370typedef int64_t (*alarm_callback_t)(alarm_id_t id, void *user_data);
371
372typedef struct alarm_pool alarm_pool_t;
373
378void alarm_pool_init_default(void);
379
380#if !PICO_TIME_DEFAULT_ALARM_POOL_DISABLED
389#endif
390
409alarm_pool_t *alarm_pool_create(uint hardware_alarm_num, uint max_timers);
410
429
437
445
452
476alarm_id_t alarm_pool_add_alarm_at(alarm_pool_t *pool, absolute_time_t time, alarm_callback_t callback, void *user_data, bool fire_if_past);
477
496 void *user_data);
520static inline alarm_id_t alarm_pool_add_alarm_in_us(alarm_pool_t *pool, uint64_t us, alarm_callback_t callback, void *user_data, bool fire_if_past) {
521 return alarm_pool_add_alarm_at(pool, delayed_by_us(get_absolute_time(), us), callback, user_data, fire_if_past);
522}
523
547static inline alarm_id_t alarm_pool_add_alarm_in_ms(alarm_pool_t *pool, uint32_t ms, alarm_callback_t callback, void *user_data, bool fire_if_past) {
548 return alarm_pool_add_alarm_at(pool, delayed_by_ms(get_absolute_time(), ms), callback, user_data, fire_if_past);
549}
550
560
561#if !PICO_TIME_DEFAULT_ALARM_POOL_DISABLED
584static inline alarm_id_t add_alarm_at(absolute_time_t time, alarm_callback_t callback, void *user_data, bool fire_if_past) {
585 return alarm_pool_add_alarm_at(alarm_pool_get_default(), time, callback, user_data, fire_if_past);
586}
587
610static inline alarm_id_t add_alarm_in_us(uint64_t us, alarm_callback_t callback, void *user_data, bool fire_if_past) {
611 return alarm_pool_add_alarm_in_us(alarm_pool_get_default(), us, callback, user_data, fire_if_past);
612}
613
636static inline alarm_id_t add_alarm_in_ms(uint32_t ms, alarm_callback_t callback, void *user_data, bool fire_if_past) {
637 return alarm_pool_add_alarm_in_ms(alarm_pool_get_default(), ms, callback, user_data, fire_if_past);
638}
646static inline bool cancel_alarm(alarm_id_t alarm_id) {
648}
649
650#endif
651
663
671
678 int64_t delay_us;
679 alarm_pool_t *pool;
680 alarm_id_t alarm_id;
682 void *user_data;
683};
684
703bool alarm_pool_add_repeating_timer_us(alarm_pool_t *pool, int64_t delay_us, repeating_timer_callback_t callback, void *user_data, repeating_timer_t *out);
704
723static inline bool alarm_pool_add_repeating_timer_ms(alarm_pool_t *pool, int32_t delay_ms, repeating_timer_callback_t callback, void *user_data, repeating_timer_t *out) {
724 return alarm_pool_add_repeating_timer_us(pool, delay_ms * (int64_t)1000, callback, user_data, out);
725}
726
727#if !PICO_TIME_DEFAULT_ALARM_POOL_DISABLED
745static inline bool add_repeating_timer_us(int64_t delay_us, repeating_timer_callback_t callback, void *user_data, repeating_timer_t *out) {
746 return alarm_pool_add_repeating_timer_us(alarm_pool_get_default(), delay_us, callback, user_data, out);
747}
748
766static inline bool add_repeating_timer_ms(int32_t delay_ms, repeating_timer_callback_t callback, void *user_data, repeating_timer_t *out) {
767 return alarm_pool_add_repeating_timer_us(alarm_pool_get_default(), delay_ms * (int64_t)1000, callback, user_data, out);
768}
769#endif
770
779
780#ifdef __cplusplus
781}
782#endif
783
784#endif
bool alarm_pool_cancel_alarm(alarm_pool_t *pool, alarm_id_t alarm_id)
Cancel an alarm.
Definition time.c:293
static alarm_id_t alarm_pool_add_alarm_in_us(alarm_pool_t *pool, uint64_t us, alarm_callback_t callback, void *user_data, bool fire_if_past)
Add an alarm callback to be called after a delay specified in microseconds.
Definition time.h:520
alarm_pool_t * alarm_pool_create(uint hardware_alarm_num, uint max_timers)
Create an alarm pool.
Definition time.c:180
uint alarm_pool_hardware_alarm_num(alarm_pool_t *pool)
Return the hardware alarm used by an alarm pool.
Definition time.c:318
uint alarm_pool_core_num(alarm_pool_t *pool)
Return the core number the alarm pool was initialized on (and hence callbacks are called on)
Definition time.c:322
alarm_pool_t * alarm_pool_get_default(void)
The default alarm pool used when alarms are added without specifying an alarm pool,...
Definition time.c:93
static alarm_id_t add_alarm_in_us(uint64_t us, alarm_callback_t callback, void *user_data, bool fire_if_past)
Add an alarm callback to be called after a delay specified in microseconds.
Definition time.h:610
static alarm_id_t alarm_pool_add_alarm_in_ms(alarm_pool_t *pool, 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:547
alarm_pool_t * alarm_pool_create_with_unused_hardware_alarm(uint max_timers)
Create an alarm pool, claiming an used hardware alarm to back it.
Definition time.c:190
alarm_id_t alarm_pool_add_alarm_at_force_in_context(alarm_pool_t *pool, absolute_time_t time, alarm_callback_t callback, void *user_data)
Add an alarm callback to be called at or after a specific time.
Definition time.c:273
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:636
int32_t alarm_id_t
The identifier for an alarm.
Definition time.h:359
void alarm_pool_init_default(void)
Create the default alarm pool (if not already created or disabled)
Definition time.c:78
alarm_id_t alarm_pool_add_alarm_at(alarm_pool_t *pool, absolute_time_t time, alarm_callback_t callback, void *user_data, bool fire_if_past)
Add an alarm callback to be called at a specific time.
Definition time.c:226
int64_t(* alarm_callback_t)(alarm_id_t id, void *user_data)
User alarm callback.
Definition time.h:370
void alarm_pool_destroy(alarm_pool_t *pool)
Destroy the alarm pool, cancelling all alarms and freeing up the underlying hardware alarm.
Definition time.c:208
static alarm_id_t add_alarm_at(absolute_time_t time, alarm_callback_t callback, void *user_data, bool fire_if_past)
Add an alarm callback to be called at a specific time.
Definition time.h:584
static bool cancel_alarm(alarm_id_t alarm_id)
Cancel an alarm from the default alarm pool.
Definition time.h:646
uint64_t time_us_64(void)
Return the current 64 bit timestamp value in microseconds.
Definition timer.c:41
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:766
bool(* repeating_timer_callback_t)(repeating_timer_t *rt)
Callback for a repeating timer.
Definition time.h:670
bool alarm_pool_add_repeating_timer_us(alarm_pool_t *pool, int64_t delay_us, 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 microseconds.
Definition time.c:346
static bool add_repeating_timer_us(int64_t delay_us, 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 microseconds.
Definition time.h:745
bool cancel_repeating_timer(repeating_timer_t *timer)
Cancel a repeating timer.
Definition time.c:359
static bool alarm_pool_add_repeating_timer_ms(alarm_pool_t *pool, 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:723
void sleep_until(absolute_time_t target)
Wait until after the given timestamp to return.
Definition time.c:382
void sleep_ms(uint32_t ms)
Wait for the given number of milliseconds before returning.
Definition time.c:429
bool best_effort_wfe_or_timeout(absolute_time_t timeout_timestamp)
Helper method for blocking on a timeout.
Definition time.c:433
void sleep_us(uint64_t us)
Wait for the given number of microseconds before returning.
Definition time.c:412
static bool is_nil_time(absolute_time_t t)
Determine if the given timestamp is nil.
Definition time.h:199
static uint64_t to_us_since_boot(absolute_time_t t)
convert an absolute_time_t into a number of microseconds since boot.
Definition types.h:44
static int64_t absolute_time_diff_us(absolute_time_t from, absolute_time_t to)
Return the difference in microseconds between two timestamps.
Definition time.h:156
static bool is_at_the_end_of_time(absolute_time_t t)
Determine if the given timestamp is "at_the_end_of_time".
Definition time.h:184
static absolute_time_t absolute_time_min(absolute_time_t a, absolute_time_t b)
Return the earlier of two timestamps.
Definition time.h:167
static absolute_time_t get_absolute_time(void)
Return a representation of the current time.
Definition time.h:61
static absolute_time_t make_timeout_time_us(uint64_t us)
Convenience method to get the timestamp a number of microseconds from the current time.
Definition time.h:131
static absolute_time_t delayed_by_us(const absolute_time_t t, uint64_t us)
Return a timestamp value obtained by adding a number of microseconds to another timestamp.
Definition time.h:94
static absolute_time_t delayed_by_ms(const absolute_time_t t, uint32_t ms)
Return a timestamp value obtained by adding a number of milliseconds to another timestamp.
Definition time.h:113
const absolute_time_t nil_time
The timestamp representing a null timestamp.
static absolute_time_t make_timeout_time_ms(uint32_t ms)
Convenience method to get the timestamp a number of milliseconds from the current time.
Definition time.h:141
static uint32_t to_ms_since_boot(absolute_time_t t)
Convert a timestamp into a number of milliseconds since boot.
Definition time.h:82
const absolute_time_t at_the_end_of_time
The timestamp representing the end of time; this is actually not the maximum possible timestamp,...
static void update_us_since_boot(absolute_time_t *t, uint64_t us_since_boot)
update an absolute_time_t value to represent a given number of microseconds since boot
Definition types.h:59
Definition types.h:33
Definition time.c:25
Information about a repeating timer.
Definition time.h:677