Cleans up userspace headers
[akaros.git] / user / benchutil / include / alarm.h
1 /* Copyright (c) 2013 The Regents of the University of California
2  * Barret Rhoden <brho@cs.berkeley.edu>
3  * See LICENSE for details.
4  *
5  * Userspace alarm service, based off a slimmed down version of the kernel
6  * alarms.  Under the hood, it uses the kernel alarm service for the root of
7  * the alarm chain.
8  *
9  * This is (was) hanging out in benchutil so as to not create a dependency from
10  * parlib on benchutil (usec2tsc and friends).
11  *
12  * There's only one timer chain, unlike in the kernel, for the entire process.
13  * If you want one-off timers unrelated to the chain (and sent to other vcores),
14  * use #A directly.
15  *
16  * Your handlers will run from vcore context.
17  *
18  * 1) To set a handler to run on an alarm:
19  *      struct alarm_waiter *waiter = malloc(sizeof(struct alarm_waiter));
20  *      init_awaiter(waiter, HANDLER);
21  *      waiter->data = something;
22  *      set_awaiter_rel(waiter, USEC);
23  *      set_alarm(waiter);
24  * If you want the HANDLER to run again, do this at the end of it:
25  *      set_awaiter_rel(waiter, USEC);
26  *      __set_alarm(waiter);
27  * Do not call set_alarm() from within an alarm handler; you'll deadlock.
28  * Don't forget to manage your memory at some (safe) point:
29  *      free(waiter); */
30
31 #ifndef BENCHUTIL_ALARM_H
32 #define BENCHUTIL_ALARM_H
33
34 #include <ros/common.h>
35 #include <sys/queue.h>
36 #include <spinlock.h>
37 #include <event.h>
38
39 __BEGIN_DECLS
40
41 /* Specifc waiter, per alarm */
42 struct alarm_waiter {
43         uint64_t                                        wake_up_time;   /* tsc time */
44         void (*func) (struct alarm_waiter *waiter);
45         void                                            *data;
46         TAILQ_ENTRY(alarm_waiter)       next;
47         bool                                            on_tchain;
48 };
49 TAILQ_HEAD(awaiters_tailq, alarm_waiter);               /* ideally not a LL */
50
51 typedef void (*alarm_handler)(struct alarm_waiter *waiter);
52
53 /* Sorted collection of alarms. */
54 struct timer_chain {
55         struct spin_pdr_lock            lock;
56         struct awaiters_tailq           waiters;
57         uint64_t                                        earliest_time;
58         uint64_t                                        latest_time;
59         int                                                     ctlfd;
60         int                                                     timerfd;
61         int                                                     alarmid;
62         struct event_queue                      *ev_q;
63 };
64
65 /* For fresh alarm waiters.  func == 0 for kthreads */
66 void init_awaiter(struct alarm_waiter *waiter,
67                   void (*func) (struct alarm_waiter *));
68 /* Sets the time an awaiter goes off */
69 void set_awaiter_abs(struct alarm_waiter *waiter, uint64_t abs_time);
70 void set_awaiter_abs_unix(struct alarm_waiter *waiter, uint64_t abs_time);
71 void set_awaiter_rel(struct alarm_waiter *waiter, uint64_t usleep);
72 void set_awaiter_inc(struct alarm_waiter *waiter, uint64_t usleep);
73 /* Arms/disarms the alarm */
74 void __set_alarm(struct alarm_waiter *waiter);
75 void set_alarm(struct alarm_waiter *waiter);
76 bool unset_alarm(struct alarm_waiter *waiter);
77 void reset_alarm_abs(struct alarm_waiter *waiter, uint64_t abs_time);
78
79 /* "parlib" alarm handlers */
80 void alarm_abort_sysc(struct alarm_waiter *awaiter);
81
82 /* Debugging */
83 #define ALARM_POISON_TIME 12345
84 void print_chain(struct timer_chain *tchain);
85
86 __END_DECLS
87
88 #endif /* BENCHUTIL_ALARM_H */