summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRichard Braun <rbraun@sceen.net>2019-07-12 00:34:51 +0200
committerRichard Braun <rbraun@sceen.net>2019-08-16 03:57:13 +0200
commit204eec9be03f53b93d0f732c967a623f8e0843ef (patch)
tree491092a44d3a6193ad9cd21ca34a3ba10fdd79f2
parenta62edad69f70d1c86dfa51cc8a2e298bb966180b (diff)
Document the timer API
-rw-r--r--kern/timer.c2
-rw-r--r--kern/timer.h23
-rw-r--r--kern/timer_i.h2
3 files changed, 17 insertions, 10 deletions
diff --git a/kern/timer.c b/kern/timer.c
index 9495c0f2..979ee5ea 100644
--- a/kern/timer.c
+++ b/kern/timer.c
@@ -435,7 +435,7 @@ INIT_OP_DEFINE(timer_setup,
INIT_OP_DEP(spinlock_setup, true));
void
-timer_init(struct timer *timer, timer_fn_t fn, int flags)
+timer_init(struct timer *timer, timer_handler_fn_t fn, int flags)
{
timer->fn = fn;
timer->cpu = TIMER_INVALID_CPU;
diff --git a/kern/timer.h b/kern/timer.h
index 02b5bef7..9ebfd0e7 100644
--- a/kern/timer.h
+++ b/kern/timer.h
@@ -35,9 +35,11 @@
struct timer;
/*
- * Type for timer functions.
+ * Type for timer callbacks.
+ *
+ * These functions implement handler operations.
*/
-typedef void (*timer_fn_t)(struct timer *);
+typedef void (*timer_handler_fn_t)(struct timer *);
#include <kern/timer_i.h>
@@ -59,7 +61,7 @@ timer_get_time(const struct timer *timer)
* Timers that are reponsible for releasing their own resources must
* be detached.
*/
-void timer_init(struct timer *timer, timer_fn_t fn, int flags);
+void timer_init(struct timer *timer, timer_handler_fn_t fn, int flags);
/*
* Schedule a timer.
@@ -67,11 +69,13 @@ void timer_init(struct timer *timer, timer_fn_t fn, int flags);
* The time of expiration is an absolute time in ticks.
*
* Timers may safely be rescheduled after completion. Periodic timers are
- * implemented by rescheduling from the handler.
+ * implemented by rescheduling from the timer handler.
*
* If the timer has been canceled, this function does nothing. A
* canceled timer must be reinitialized before being scheduled again.
*
+ * This operation synchronizes with handler operations on the same timer.
+ *
* This function may safely be called in interrupt context.
*/
void timer_schedule(struct timer *timer, uint64_t ticks);
@@ -81,13 +85,16 @@ void timer_schedule(struct timer *timer, uint64_t ticks);
*
* The given timer must not be detached.
*
- * If the timer has already expired, this function waits until the timer
- * function completes, or returns immediately if the function has already
- * completed.
+ * If the timer is still scheduled, it is canceled, i.e. its handler
+ * operation won't start. Otherwise, if the timer has already expired,
+ * this function waits until the handler operation completes, or returns
+ * immediately if the handler operation has already completed.
*
* This function may safely be called from the timer handler, but not on
- * the current timer. Canceling a timer from the handler is achieved by
+ * the same timer. Canceling a timer from the timer handler is achieved by
* simply not rescheduling it.
+ *
+ * Handler operations on the same timer synchronize with this operation.
*/
void timer_cancel(struct timer *timer);
diff --git a/kern/timer_i.h b/kern/timer_i.h
index 799b5ac9..6f5b69ed 100644
--- a/kern/timer_i.h
+++ b/kern/timer_i.h
@@ -40,7 +40,7 @@ struct timer {
};
uint64_t ticks; /* (c) */
- timer_fn_t fn;
+ timer_handler_fn_t fn;
unsigned int cpu; /* (c,a,*) */
unsigned short state; /* (c) */
unsigned short flags; /* (c) */