1 // Copyright (c) 2008-2009 Travis Geiselbrecht
2 //
3 // Use of this source code is governed by a MIT-style
4 // license that can be found in the LICENSE file or at
5 // https://opensource.org/licenses/MIT
6 #pragma once
7 
8 #include <lk/compiler.h>
9 #include <lk/list.h>
10 #include <sys/types.h>
11 #include <stdint.h>
12 
13 // This file defines the timer API for the LK kernel.
14 // Timers are used to schedule callbacks to occur at a specific time in the future.
15 
16 // Rules for Timers:
17 // - Timer callbacks occur from interrupt context.
18 // - Timers may be programmed or canceled from interrupt or thread context.
19 // - Timers may be canceled or reprogrammed from within their callback.
20 //
21 
22 __BEGIN_CDECLS
23 
24 // Initializes the timer subsystem.
25 void timer_init(void);
26 
27 struct timer;
28 typedef enum handler_return (*timer_callback)(struct timer *, lk_time_t now, void *arg);
29 
30 #define TIMER_MAGIC (0x74696D72)  //'timr'
31 
32 typedef struct timer {
33     uint32_t magic;
34     struct list_node node;
35 
36     lk_time_t scheduled_time;
37     lk_time_t periodic_time;
38 
39     timer_callback callback;
40     void *arg;
41 } timer_t;
42 
43 // Initializes a timer to the default state. Can statically initialize a timer
44 // with the TIMER_INITIAL_VALUE macro or dynamically initialize it with timer_initialize().
45 #define TIMER_INITIAL_VALUE(t) \
46 { \
47     .magic = TIMER_MAGIC, \
48     .node = LIST_INITIAL_CLEARED_VALUE, \
49     .scheduled_time = 0, \
50     .periodic_time = 0, \
51     .callback = NULL, \
52     .arg = NULL, \
53 }
54 
55 void timer_initialize(timer_t *);
56 
57 // Sets a timer to fire once after a delay.
58 void timer_set_oneshot(timer_t *, lk_time_t delay, timer_callback, void *arg);
59 
60 // Sets a timer to fire periodically at the specified interval.
61 void timer_set_periodic(timer_t *, lk_time_t period, timer_callback, void *arg);
62 
63 // Cancels a timer, removing it from the timer queue and preventing it from firing.
64 // If the timer is currently running, it will not be canceled until the callback returns.
65 // May be called from interrupt or thread context.
66 // The callback will not be called again after this.
67 void timer_cancel(timer_t *);
68 
69 __END_CDECLS
70