Outline ![]()
Files ![]()
loading...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
/*
* Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
#ifndef _PICO_TIME_H
#define _PICO_TIME_H
#include "pico.h"
#include "hardware/timer.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file time.h
* \defgroup pico_time pico_time
*
* \brief API for accurate timestamps, sleeping, and time based callbacks
*
* \note The functions defined here provide a much more powerful and user friendly wrapping around the
* low level hardware timer functionality. For these functions (and any other SDK functionality
* e.g. timeouts, that relies on them) to work correctly, the hardware timer should not be modified. i.e. it is expected
* to be monotonically increasing once per microsecond. Fortunately there is no need to modify the hardware
* timer as any functionality you can think of that isn't already covered here can easily be modelled
* by adding or subtracting a constant value from the unmodified hardware timer.
*
* \sa \ref hardware_timer
*/
// PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_PICO_TIME, Enable/disable assertions in the pico_time module, type=bool, default=0, group=pico_time
#ifndef PARAM_ASSERTIONS_ENABLED_PICO_TIME
#ifdef PARAM_ASSERTIONS_ENABLED_PICO_TIME // backwards compatibility with SDK < 2.0.0
#define PARAM_ASSERTIONS_ENABLED_PICO_TIME PARAM_ASSERTIONS_ENABLED_TIME
#else
#define PARAM_ASSERTIONS_ENABLED_PICO_TIME 0
#endif
#endif
// 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
#ifndef PICO_TIME_SLEEP_OVERHEAD_ADJUST_US
#define PICO_TIME_SLEEP_OVERHEAD_ADJUST_US 6
#endif
/*!
* \defgroup timestamp timestamp
* \ingroup pico_time
* \brief Timestamp functions relating to points in time (including the current time).
*
* These are functions for dealing with timestamps (i.e. instants in time) represented by the type absolute_time_t. This opaque
* type is provided to help prevent accidental mixing of timestamps and relative time values.
*/
/*! \brief Return a representation of the current time.
* \ingroup timestamp
*
* Returns an opaque high fidelity representation of the current time sampled during the call.
*
* \return the absolute time (now) of the hardware timer
*
* \sa absolute_time_t
* \sa sleep_until()
* \sa time_us_64()
*/
static inline absolute_time_t get_absolute_time(void) {
absolute_time_t t;
update_us_since_boot(&t, time_us_64());
return t;
}
static inline uint32_t us_to_ms(uint64_t us) {
if (us >> 32u) {
return (uint32_t)(us / 1000u);
} else {
return ((uint32_t)us) / 1000u;
}
}
/*! fn to_ms_since_boot
* \ingroup timestamp
* \brief Convert a timestamp into a number of milliseconds since boot.
* \param t an absolute_time_t value to convert
* \return the number of milliseconds since boot represented by t
* \sa to_us_since_boot()
*/
static inline uint32_t to_ms_since_boot(absolute_time_t t) {
uint64_t us = to_us_since_boot(t);
return us_to_ms(us);
}
/*! \brief Return a timestamp value obtained by adding a number of microseconds to another timestamp
* \ingroup timestamp
*
* \param t the base timestamp
* \param us the number of microseconds to add
* \return the timestamp representing the resulting time
*/
static inline absolute_time_t delayed_by_us(const absolute_time_t t, uint64_t us) {
absolute_time_t t2;
uint64_t base = to_us_since_boot(t);
uint64_t delayed = base + us;
if ((int64_t)delayed < 0) {
// absolute_time_t (to allow for signed time deltas) is never greater than INT64_MAX which == at_the_end_of_time
delayed = INT64_MAX;
}
update_us_since_boot(&t2, delayed);
return t2;
}
/*! \brief Return a timestamp value obtained by adding a number of milliseconds to another timestamp
* \ingroup timestamp
*
* \param t the base timestamp
* \param ms the number of milliseconds to add
* \return the timestamp representing the resulting time
*/
static inline absolute_time_t delayed_by_ms(const absolute_time_t t, uint32_t ms) {
absolute_time_t t2;
uint64_t base = to_us_since_boot(t);
uint64_t delayed = base + ms * 1000ull;
if ((int64_t)delayed < 0) {
// absolute_time_t (to allow for signed time deltas) is never greater than INT64_MAX which == at_the_end_of_time
delayed = INT64_MAX;
}
update_us_since_boot(&t2, delayed);
return t2;
}
/*! \brief Convenience method to get the timestamp a number of microseconds from the current time
* \ingroup timestamp
*
* \param us the number of microseconds to add to the current timestamp
* \return the future timestamp
*/
static inline absolute_time_t make_timeout_time_us(uint64_t us) {
return delayed_by_us(get_absolute_time(), us);
}
/*! \brief Convenience method to get the timestamp a number of milliseconds from the current time
* \ingroup timestamp
*
* \param ms the number of milliseconds to add to the current timestamp
* \return the future timestamp
*/
static inline absolute_time_t make_timeout_time_ms(uint32_t ms) {
return delayed_by_ms(get_absolute_time(), ms);
}
/*! \brief Return the difference in microseconds between two timestamps
* \ingroup timestamp
*
* \note be careful when diffing against large timestamps (e.g. \ref at_the_end_of_time)
* as the signed integer may overflow.
*
* \param from the first timestamp
* \param to the second timestamp
* \return the number of microseconds between the two timestamps (positive if `to` is after `from` except
* in case of overflow)
*/
static inline int64_t absolute_time_diff_us(absolute_time_t from, absolute_time_t to) {
return (int64_t)(to_us_since_boot(to) - to_us_since_boot(from));
}
/*! \brief Return the earlier of two timestamps
* \ingroup timestamp
*
* \param a the first timestamp
* \param b the second timestamp
* \return the earlier of the two timestamps
*/
static inline absolute_time_t absolute_time_min(absolute_time_t a, absolute_time_t b) {
return to_us_since_boot(a) < to_us_since_boot(b) ? a : b;
}
/*! \brief The timestamp representing the end of time; this is actually not the maximum possible
* timestamp, but is set to 0x7fffffff_ffffffff microseconds to avoid sign overflows with time
* arithmetic. This is almost 300,000 years, so should be sufficient.
* \ingroup timestamp
*/
extern const absolute_time_t at_the_end_of_time;
/*! \brief Determine if the given timestamp is "at_the_end_of_time"
* \ingroup timestamp
* \param t the timestamp
* \return true if the timestamp is at_the_end_of_time
* \sa at_the_end_of_time
*/
static inline bool is_at_the_end_of_time(absolute_time_t t) {
return to_us_since_boot(t) == to_us_since_boot(at_the_end_of_time);
}
/*! \brief The timestamp representing a null timestamp
* \ingroup timestamp
*/
extern const absolute_time_t nil_time;
/*! \brief Determine if the given timestamp is nil
* \ingroup timestamp
* \param t the timestamp
* \return true if the timestamp is nil
* \sa nil_time
*/
static inline bool is_nil_time(absolute_time_t t) {
return !to_us_since_boot(t);
}
/*!
* \defgroup sleep sleep
* \ingroup pico_time
* \brief Sleep functions for delaying execution in a lower power state.
*
* These functions allow the calling core to sleep. This is a lower powered sleep; waking and re-checking time on every processor
* event (WFE)
*
* \note These functions should not be called from an IRQ handler.
*
* \note Lower powered sleep requires use of the \link alarm_pool_get_default default alarm pool\endlink which may
* be disabled by the PICO_TIME_DEFAULT_ALARM_POOL_DISABLED #define or currently full in which case these functions
* become busy waits instead.
*
* \note Whilst \a sleep_ functions are preferable to \a busy_wait functions from a power perspective, the \a busy_wait equivalent function
* may return slightly sooner after the target is reached.
*
* \sa busy_wait_until() \sa busy_wait_us() \sa busy_wait_us_32()
*/
/*! \brief Wait until after the given timestamp to return
* \ingroup sleep
*
* \note This method attempts to perform a lower power (WFE) sleep
*
* \param target the time after which to return
* \sa sleep_us()
* \sa busy_wait_until()
* */
void sleep_until(absolute_time_t target);
/*! \brief Wait for the given number of microseconds before returning
* \ingroup sleep
*
* \note This method attempts to perform a lower power (WFE) sleep
*
* \param us the number of microseconds to sleep
* \sa busy_wait_us()
*/
void sleep_us(uint64_t us);
/*! \brief Wait for the given number of milliseconds before returning
* \ingroup sleep
*
* \note This method attempts to perform a lower power sleep (using WFE) as much as possible.
*
* \param ms the number of milliseconds to sleep
*/
void sleep_ms(uint32_t ms);
/*! \brief Helper method for blocking on a timeout
* \ingroup sleep
*
* This method will return in response to an event (as per __wfe) or
* when the target time is reached, or at any point before.
*
* This method can be used to implement a lower power polling loop waiting on
* some condition signalled by an event (__sev()).
*
* This is called \a best_effort because under certain circumstances (notably the default timer pool
* being disabled or full) the best effort is simply to return immediately without a __wfe, thus turning the calling
* code into a busy wait.
*
* Example usage:
* ```c
* bool my_function_with_timeout_us(uint64_t timeout_us) {
* absolute_time_t timeout_time = make_timeout_time_us(timeout_us);
* do {
* // each time round the loop, we check to see if the condition
* // we are waiting on has happened
* if (my_check_done()) {
* // do something
* return true;
* }
* // will try to sleep until timeout or the next processor event
* } while (!best_effort_wfe_or_timeout(timeout_time));
* return false; // timed out
* }
* ```
*
* @param timeout_timestamp the timeout time
* @return true if the target time is reached, false otherwise
*/
bool best_effort_wfe_or_timeout(absolute_time_t timeout_timestamp);
/*!
* \defgroup alarm alarm
* \ingroup pico_time
* \brief Alarm functions for scheduling future execution
*
* Alarms are added to alarm pools, which may hold a certain fixed number of active alarms. Each alarm pool
* utilizes one of four underlying timer_alarms, thus you may have up to four alarm pools. An alarm pool
* calls (except when the callback would happen before or during being set) the callback on the core from which
* the alarm pool was created. Callbacks are called from the timer_alarm IRQ handler, so care must
* be taken in their implementation.
*
* A default pool is created the core specified by PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM
* on core 0, and may be used by the method variants that take no alarm pool parameter.
*
* \sa struct alarm_pool
* \sa hardware_timer
*/
// PICO_CONFIG: PICO_TIME_DEFAULT_ALARM_POOL_DISABLED, Disable the default alarm pool, type=bool, default=0, advanced=true, group=pico_time
#ifndef PICO_TIME_DEFAULT_ALARM_POOL_DISABLED
/*!
* \brief If 1 then the default alarm pool is disabled (so no timer_alarm is claimed for the pool)
*
* \note Setting to 1 may cause some code not to compile as default timer pool related methods are removed
*
* \note When the default alarm pool is disabled, \a sleep_ methods and timeouts are no longer lower powered
* (they become \a busy_wait_)
*
* \ingroup alarm
* \sa #PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM
* \sa alarm_pool_get_default()
*/
#define PICO_TIME_DEFAULT_ALARM_POOL_DISABLED 0
#endif
// 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
#ifndef PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM
/*!
* \brief Selects which timer_alarm is used for the default alarm pool
* \ingroup alarm
* \sa alarm_pool_get_default()
*/
#define PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM 3
#endif
// 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
#ifndef PICO_TIME_DEFAULT_ALARM_POOL_MAX_TIMERS
/*!
* \brief Selects the maximum number of concurrent timers in the default alarm pool
* \ingroup alarm
*
* \note For implementation reasons this is limited to PICO_PHEAP_MAX_ENTRIES which defaults to 255
* \sa #PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM
* \sa alarm_pool_get_default()
*/
#define PICO_TIME_DEFAULT_ALARM_POOL_MAX_TIMERS 16
#endif
/**
* \brief The identifier for an alarm
*
* \note this identifier is signed because <0 is used as an error condition when creating alarms
*
* \note alarm ids may be reused, however for convenience the implementation makes an attempt to defer
* reusing as long as possible. You should certainly expect it to be hundreds of ids before one is
* reused, although in most cases it is more. Nonetheless care must still be taken when cancelling
* alarms or other functionality based on alarms when the alarm may have expired, as eventually
* the alarm id may be reused for another alarm.
*
* \see pico_error_codes
* \ingroup alarm
*/
typedef int32_t alarm_id_t; // note this is signed because we use <0 as a meaningful error value
/**
* \brief User alarm callback
* \ingroup alarm
* \param id the alarm_id as returned when the alarm was added
* \param user_data the user data passed when the alarm was added
* \return <0 to reschedule the same alarm this many us from the time the alarm was previously scheduled to fire
* \return >0 to reschedule the same alarm this many us from the time this method returns
* \return 0 to not reschedule the alarm
*/
typedef int64_t (*alarm_callback_t)(alarm_id_t id, void *user_data);
typedef struct alarm_pool alarm_pool_t;
typedef void alarm_pool_timer_t;
/**
* \brief Create the default alarm pool (if not already created or disabled)
* \ingroup alarm
*/
void alarm_pool_init_default(void);
void runtime_init_default_alarm_pool(void);
#if !PICO_TIME_DEFAULT_ALARM_POOL_DISABLED
/*!
* \brief The default alarm pool used when alarms are added without specifying an alarm pool,
* and also used by the SDK to support lower power sleeps and timeouts.
*
* \ingroup alarm
* \sa #PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM
*/
alarm_pool_t *alarm_pool_get_default(void);
#endif
alarm_pool_t *alarm_pool_create_on_timer(alarm_pool_timer_t *timer, uint timer_alarm_num, uint max_timers);
alarm_pool_timer_t *alarm_pool_timer_for_timer_num(uint timer_num);
alarm_pool_timer_t *alarm_pool_get_default_timer(void);
/**
* \brief Create an alarm pool
*
* The alarm pool will call callbacks from an alarm IRQ Handler on the core of this function is called from.
*
* In many situations there is never any need for anything other than the default alarm pool, however you
* might want to create another if you want alarm callbacks on core 1 or require alarm pools of
* different priority (IRQ priority based preemption of callbacks)
*
* \note This method will hard assert if the timer_alarm is already claimed.
*
* \ingroup alarm
* \param timer_alarm_num the timer_alarm to use to back this pool
* \param max_timers the maximum number of timers
* \note For implementation reasons this is limited to PICO_PHEAP_MAX_ENTRIES which defaults to 255
* \sa alarm_pool_get_default()
* \sa hardware_claiming
*/
static inline alarm_pool_t *alarm_pool_create(uint timer_alarm_num, uint max_timers) {
return alarm_pool_create_on_timer(alarm_pool_get_default_timer(), timer_alarm_num, max_timers);
}
alarm_pool_t *alarm_pool_create_on_timer_with_unused_hardware_alarm(alarm_pool_timer_t *timer, uint max_timers);
/**
* \brief Create an alarm pool, claiming an used timer_alarm to back it.
*
* The alarm pool will call callbacks from an alarm IRQ Handler on the core of this function is called from.
*
* In many situations there is never any need for anything other than the default alarm pool, however you
* might want to create another if you want alarm callbacks on core 1 or require alarm pools of
* different priority (IRQ priority based preemption of callbacks)
*
* \note This method will hard assert if the there is no free hardware to claim.
*
* \ingroup alarm
* \param max_timers the maximum number of timers
* \note For implementation reasons this is limited to PICO_PHEAP_MAX_ENTRIES which defaults to 255
* \sa alarm_pool_get_default()
* \sa hardware_claiming
*/
static inline alarm_pool_t *alarm_pool_create_with_unused_hardware_alarm(uint max_timers) {
return alarm_pool_create_on_timer_with_unused_hardware_alarm(alarm_pool_get_default_timer(), max_timers);
}
/**
* \brief Return the timer alarm used by an alarm pool
* \ingroup alarm
* \param pool the pool
* \return the timer_alarm used by the pool
*/
uint alarm_pool_timer_alarm_num(alarm_pool_t *pool);
// backwards compatibility
static inline uint alarm_pool_hardware_alarm_num(alarm_pool_t *pool) {
return alarm_pool_timer_alarm_num(pool);
}
/**
* \brief Return the core number the alarm pool was initialized on (and hence callbacks are called on)
* \ingroup alarm
* \param pool the pool
* \return the core used by the pool
*/
uint alarm_pool_core_num(alarm_pool_t *pool);
/**
* \brief Destroy the alarm pool, cancelling all alarms and freeing up the underlying timer_alarm
* \ingroup alarm
* \param pool the pool
*/
void alarm_pool_destroy(alarm_pool_t *pool);
/*!
* \brief Add an alarm callback to be called at a specific time
* \ingroup alarm
*
* Generally the callback is called as soon as possible after the time specified from an IRQ handler
* on the core the alarm pool was created on. If the callback is in the past or happens before
* the alarm setup could be completed, then this method will optionally call the callback itself
* and then return a return code to indicate that the target time has passed.
*
* \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
*
* @param pool the alarm pool to use for scheduling the callback (this determines which timer_alarm is used, and which core calls the callback)
* @param time the timestamp when (after which) the callback should fire
* @param callback the callback function
* @param user_data user data to pass to the callback function
* @param fire_if_past if true, and the alarm time falls before or during this call before the alarm can be set,
* then the callback should be called during (by) this function instead
* @return >0 the alarm id for an active (at the time of return) alarm
* @return 0 if the alarm time passed before or during the call and fire_if_past was false
* @return <0 if there were no alarm slots available, or other error occurred
*/
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);
/*!
* \brief Add an alarm callback to be called at or after a specific time
* \ingroup alarm
*
* The callback is called as soon as possible after the time specified from an IRQ handler
* on the core the alarm pool was created on. Unlike \ref alarm_pool_add_alarm_at, this method
* guarantees to call the callback from that core even if the time is during this method call or in the past.
*
* \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
*
* @param pool the alarm pool to use for scheduling the callback (this determines which timer_alarm is used, and which core calls the callback)
* @param time the timestamp when (after which) the callback should fire
* @param callback the callback function
* @param user_data user data to pass to the callback function
* @return >0 the alarm id for an active (at the time of return) alarm
* @return <0 if there were no alarm slots available, or other error occurred
*/
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);
/*!
* \brief Add an alarm callback to be called after a delay specified in microseconds
* \ingroup alarm
*
* Generally the callback is called as soon as possible after the time specified from an IRQ handler
* on the core the alarm pool was created on. If the callback is in the past or happens before
* the alarm setup could be completed, then this method will optionally call the callback itself
* and then return a return code to indicate that the target time has passed.
*
* \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
*
* @param pool the alarm pool to use for scheduling the callback (this determines which timer_alarm is used, and which core calls the callback)
* @param us the delay (from now) in microseconds when (after which) the callback should fire
* @param callback the callback function
* @param user_data user data to pass to the callback function
* @param fire_if_past if true, and the alarm time falls during this call before the alarm can be set,
* then the callback should be called during (by) this function instead
* @return >0 the alarm id
* @return 0 if the alarm time passed before or during the call and fire_if_past was false
* @return <0 if there were no alarm slots available, or other error occurred
*/
static 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) {
return alarm_pool_add_alarm_at(pool, delayed_by_us(get_absolute_time(), us), callback, user_data, fire_if_past);
}
/*!
* \brief Add an alarm callback to be called after a delay specified in milliseconds
* \ingroup alarm
*
* Generally the callback is called as soon as possible after the time specified from an IRQ handler
* on the core the alarm pool was created on. If the callback is in the past or happens before
* the alarm setup could be completed, then this method will optionally call the callback itself
* and then return a return code to indicate that the target time has passed.
*
* \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
*
* @param pool the alarm pool to use for scheduling the callback (this determines which timer_alarm is used, and which core calls the callback)
* @param ms the delay (from now) in milliseconds when (after which) the callback should fire
* @param callback the callback function
* @param user_data user data to pass to the callback function
* @param fire_if_past if true, and the alarm time falls before or during this call before the alarm can be set,
* then the callback should be called during (by) this function instead
* @return >0 the alarm id
* @return 0 if the alarm time passed before or during the call and fire_if_past was false
* @return <0 if there were no alarm slots available, or other error occurred
*/
static 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) {
return alarm_pool_add_alarm_at(pool, delayed_by_ms(get_absolute_time(), ms), callback, user_data, fire_if_past);
}
/*!
* \brief Return the time remaining before the next trigger of an alarm
* \ingroup alarm
*
* @param pool the alarm_pool containing the alarm
* @param alarm_id the alarm
*
* @return >=0 the number of microseconds before the next trigger
* @return <0 if either the given alarm is not in progress or it has passed
*/
int64_t alarm_pool_remaining_alarm_time_us(alarm_pool_t *pool, alarm_id_t alarm_id);
/*!
* \brief Return the time remaining before the next trigger of an alarm
* \ingroup alarm
*
* @param pool the alarm_pool containing the alarm
* @param alarm_id the alarm
*
* @return >=0 the number of microseconds before the next trigger (INT32_MAX if the number of ms is higher than can be represented0
* @return <0 if either the given alarm is not in progress or it has passed
*/
int32_t alarm_pool_remaining_alarm_time_ms(alarm_pool_t *pool, alarm_id_t alarm_id);
/*!
* \brief Cancel an alarm
* \ingroup alarm
* \param pool the alarm_pool containing the alarm
* \param alarm_id the alarm
* \return true if the alarm was cancelled, false if it didn't exist
* \sa alarm_id_t for a note on reuse of IDs
*/
bool alarm_pool_cancel_alarm(alarm_pool_t *pool, alarm_id_t alarm_id);
#if !PICO_TIME_DEFAULT_ALARM_POOL_DISABLED
/*!
* \brief Add an alarm callback to be called at a specific time
* \ingroup alarm
*
* Generally the callback is called as soon as possible after the time specified from an IRQ handler
* on the core of the default alarm pool (generally core 0). If the callback is in the past or happens before
* the alarm setup could be completed, then this method will optionally call the callback itself
* and then return a return code to indicate that the target time has passed.
*
* \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
*
* @param time the timestamp when (after which) the callback should fire
* @param callback the callback function
* @param user_data user data to pass to the callback function
* @param fire_if_past if true, and the alarm time falls before or during this call before the alarm can be set,
* then the callback should be called during (by) this function instead
* @return >0 the alarm id
* @return 0 if the alarm time passed before or during the call and fire_if_past was false
* @return <0 if there were no alarm slots available, or other error occurred
*/
static inline alarm_id_t add_alarm_at(absolute_time_t time, alarm_callback_t callback, void *user_data, bool fire_if_past) {
return alarm_pool_add_alarm_at(alarm_pool_get_default(), time, callback, user_data, fire_if_past);
}
/*!
* \brief Add an alarm callback to be called after a delay specified in microseconds
* \ingroup alarm
*
* Generally the callback is called as soon as possible after the time specified from an IRQ handler
* on the core of the default alarm pool (generally core 0). If the callback is in the past or happens before
* the alarm setup could be completed, then this method will optionally call the callback itself
* and then return a return code to indicate that the target time has passed.
*
* \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
*
* @param us the delay (from now) in microseconds when (after which) the callback should fire
* @param callback the callback function
* @param user_data user data to pass to the callback function
* @param fire_if_past if true, and the alarm time falls during this call before the alarm can be set,
* then the callback should be called during (by) this function instead
* @return >0 the alarm id
* @return 0 if the alarm time passed before or during the call and fire_if_past was false
* @return <0 if there were no alarm slots available, or other error occurred
*/
static inline alarm_id_t add_alarm_in_us(uint64_t us, alarm_callback_t callback, void *user_data, bool fire_if_past) {
return alarm_pool_add_alarm_in_us(alarm_pool_get_default(), us, callback, user_data, fire_if_past);
}
/*!
* \brief Add an alarm callback to be called after a delay specified in milliseconds
* \ingroup alarm
*
* Generally the callback is called as soon as possible after the time specified from an IRQ handler
* on the core of the default alarm pool (generally core 0). If the callback is in the past or happens before
* the alarm setup could be completed, then this method will optionally call the callback itself
* and then return a return code to indicate that the target time has passed.
*
* \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
*
* @param ms the delay (from now) in milliseconds when (after which) the callback should fire
* @param callback the callback function
* @param user_data user data to pass to the callback function
* @param fire_if_past if true, and the alarm time falls during this call before the alarm can be set,
* then the callback should be called during (by) this function instead
* @return >0 the alarm id
* @return 0 if the alarm time passed before or during the call and fire_if_past was false
* @return <0 if there were no alarm slots available, or other error occurred
*/
static inline alarm_id_t add_alarm_in_ms(uint32_t ms, alarm_callback_t callback, void *user_data, bool fire_if_past) {
return alarm_pool_add_alarm_in_ms(alarm_pool_get_default(), ms, callback, user_data, fire_if_past);
}
/*!
* \brief Cancel an alarm from the default alarm pool
* \ingroup alarm
* \param alarm_id the alarm
* \return true if the alarm was cancelled, false if it didn't exist
* \sa alarm_id_t for a note on reuse of IDs
*/
static inline bool cancel_alarm(alarm_id_t alarm_id) {
return alarm_pool_cancel_alarm(alarm_pool_get_default(), alarm_id);
}
/*!
* \brief Return the time remaining before the next trigger of an alarm
* \ingroup alarm
*
* @param pool the alarm_pool containing the alarm
* @param alarm_id the alarm
*
* @return >=0 the number of microseconds before the next trigger
* @return <0 if either the given alarm is not in progress or it has passed
*/
int64_t remaining_alarm_time_us(alarm_id_t alarm_id);
/*!
* \brief Return the time remaining before the next trigger of an alarm
* \ingroup alarm
*
* @param alarm_id the alarm
*
* @return >=0 the number of microseconds before the next trigger (INT32_MAX if the number of ms is higher than can be represented0
* @return <0 if either the given alarm is not in progress or it has passed
*/
int32_t remaining_alarm_time_ms(alarm_id_t alarm_id);
#endif
/*!
* \defgroup repeating_timer repeating_timer
* \ingroup pico_time
* \brief Repeating Timer functions for simple scheduling of repeated execution
*
* \note The regular \a alarm_ functionality can be used to make repeating alarms (by return non zero from the callback),
* however these methods abstract that further (at the cost of a user structure to store the repeat delay in (which
* the alarm framework does not have space for).
*/
typedef struct repeating_timer repeating_timer_t;
/**
* \brief Callback for a repeating timer
* \ingroup repeating_timer
* \param rt repeating time structure containing information about the repeating time. user_data is of primary important to the user
* \return true to continue repeating, false to stop.
*/
typedef bool (*repeating_timer_callback_t)(repeating_timer_t *rt);
/**
* \brief Information about a repeating timer
* \ingroup repeating_timer
* \return
*/
struct repeating_timer {
int64_t delay_us;
alarm_pool_t *pool;
alarm_id_t alarm_id;
repeating_timer_callback_t callback;
void *user_data;
};
/*!
* \brief Add a repeating timer that is called repeatedly at the specified interval in microseconds
* \ingroup repeating_timer
*
* Generally the callback is called as soon as possible after the time specified from an IRQ handler
* on the core the alarm pool was created on. If the callback is in the past or happens before
* the alarm setup could be completed, then this method will optionally call the callback itself
* and then return a return code to indicate that the target time has passed.
*
* \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
*
* @param pool the alarm pool to use for scheduling the repeating timer (this determines which timer_alarm is used, and which core calls the callback)
* @param delay_us the repeat delay in microseconds; if >0 then this is the delay between one callback ending and the next starting; if <0 then this is the negative of the time between the starts of the callbacks. The value of 0 is treated as 1
* @param callback the repeating timer callback function
* @param user_data user data to pass to store in the repeating_timer structure for use by the callback.
* @param out the pointer to the user owned structure to store the repeating timer info in. BEWARE this storage location must outlive the repeating timer, so be careful of using stack space
* @return false if there were no alarm slots available to create the timer, true otherwise.
*/
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);
/*!
* \brief Add a repeating timer that is called repeatedly at the specified interval in milliseconds
* \ingroup repeating_timer
*
* Generally the callback is called as soon as possible after the time specified from an IRQ handler
* on the core the alarm pool was created on. If the callback is in the past or happens before
* the alarm setup could be completed, then this method will optionally call the callback itself
* and then return a return code to indicate that the target time has passed.
*
* \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
*
* @param pool the alarm pool to use for scheduling the repeating timer (this determines which timer_alarm is used, and which core calls the callback)
* @param delay_ms the repeat delay in milliseconds; if >0 then this is the delay between one callback ending and the next starting; if <0 then this is the negative of the time between the starts of the callbacks. The value of 0 is treated as 1 microsecond
* @param callback the repeating timer callback function
* @param user_data user data to pass to store in the repeating_timer structure for use by the callback.
* @param out the pointer to the user owned structure to store the repeating timer info in. BEWARE this storage location must outlive the repeating timer, so be careful of using stack space
* @return false if there were no alarm slots available to create the timer, true otherwise.
*/
static 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) {
return alarm_pool_add_repeating_timer_us(pool, delay_ms * (int64_t)1000, callback, user_data, out);
}
#if !PICO_TIME_DEFAULT_ALARM_POOL_DISABLED
/*!
* \brief Add a repeating timer that is called repeatedly at the specified interval in microseconds
* \ingroup repeating_timer
*
* Generally the callback is called as soon as possible after the time specified from an IRQ handler
* on the core of the default alarm pool (generally core 0). If the callback is in the past or happens before
* the alarm setup could be completed, then this method will optionally call the callback itself
* and then return a return code to indicate that the target time has passed.
*
* \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
*
* @param delay_us the repeat delay in microseconds; if >0 then this is the delay between one callback ending and the next starting; if <0 then this is the negative of the time between the starts of the callbacks. The value of 0 is treated as 1
* @param callback the repeating timer callback function
* @param user_data user data to pass to store in the repeating_timer structure for use by the callback.
* @param out the pointer to the user owned structure to store the repeating timer info in. BEWARE this storage location must outlive the repeating timer, so be careful of using stack space
* @return false if there were no alarm slots available to create the timer, true otherwise.
*/
static inline bool add_repeating_timer_us(int64_t delay_us, repeating_timer_callback_t callback, void *user_data, repeating_timer_t *out) {
return alarm_pool_add_repeating_timer_us(alarm_pool_get_default(), delay_us, callback, user_data, out);
}
/*!
* \brief Add a repeating timer that is called repeatedly at the specified interval in milliseconds
* \ingroup repeating_timer
*
* Generally the callback is called as soon as possible after the time specified from an IRQ handler
* on the core of the default alarm pool (generally core 0). If the callback is in the past or happens before
* the alarm setup could be completed, then this method will optionally call the callback itself
* and then return a return code to indicate that the target time has passed.
*
* \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
*
* @param delay_ms the repeat delay in milliseconds; if >0 then this is the delay between one callback ending and the next starting; if <0 then this is the negative of the time between the starts of the callbacks. The value of 0 is treated as 1 microsecond
* @param callback the repeating timer callback function
* @param user_data user data to pass to store in the repeating_timer structure for use by the callback.
* @param out the pointer to the user owned structure to store the repeating timer info in. BEWARE this storage location must outlive the repeating timer, so be careful of using stack space
* @return false if there were no alarm slots available to create the timer, true otherwise.
*/
static inline bool add_repeating_timer_ms(int32_t delay_ms, repeating_timer_callback_t callback, void *user_data, repeating_timer_t *out) {
return alarm_pool_add_repeating_timer_us(alarm_pool_get_default(), delay_ms * (int64_t)1000, callback, user_data, out);
}
#endif
/**
* \brief Cancel a repeating timer
* \ingroup repeating_timer
* \param timer the repeating timer to cancel
* \return true if the repeating timer was cancelled, false if it didn't exist
* \sa alarm_id_t for a note on reuse of IDs
*/
bool cancel_repeating_timer(repeating_timer_t *timer);
#ifdef __cplusplus
}
#endif
#endif
Details ![]()
Show: from Types: Columns: ![]( "Show Project Names")
![]( "Show Locations")
![]( "Show Referring Symbols")
![]( "Show Scope")
This file uses the notable symbols shown below. Click anywhere in the file to view more details.