[docs] provide rules for correct usage of events, mutexes, and timers
diff --git a/include/kernel/event.h b/include/kernel/event.h
index 8a7fd1f..8666737 100644
--- a/include/kernel/event.h
+++ b/include/kernel/event.h
@@ -36,6 +36,22 @@
#define EVENT_FLAG_AUTOUNSIGNAL 1
+/* Rules for Events:
+ * - Events may be signaled from interrupt context *but* the reschedule
+ * parameter must be false in that case.
+ * - Events may not be waited upon from interrupt context.
+ * - Events without FLAG_AUTOUNSIGNAL:
+ * - Wake up any waiting threads when signaled.
+ * - Continue to do so (no threads will wait) until unsignaled.
+ * - Events with FLAG_AUTOUNSIGNAL:
+ * - If one or more threads are waiting when signaled, one thread will
+ * be woken up and return. The signaled state will not be set.
+ * - If no threads are waiting when signaled, the Event will remain
+ * in the signaled state until a thread attempts to wait (at which
+ * time it will unsignal atomicly and return immediately) or
+ * event_unsignal() is called.
+*/
+
void event_init(event_t *, bool initial, uint flags);
void event_destroy(event_t *);
status_t event_wait(event_t *);
diff --git a/include/kernel/mutex.h b/include/kernel/mutex.h
index 2bdf8f4..40fe72f 100644
--- a/include/kernel/mutex.h
+++ b/include/kernel/mutex.h
@@ -34,6 +34,11 @@
wait_queue_t wait;
} mutex_t;
+/* Rules for Mutexes:
+ * - Mutexes are only safe to use from thread context.
+ * - Mutexes are non-recursive.
+*/
+
void mutex_init(mutex_t *);
void mutex_destroy(mutex_t *);
status_t mutex_acquire(mutex_t *);
diff --git a/include/kernel/timer.h b/include/kernel/timer.h
index f13ee5d..98332fd 100644
--- a/include/kernel/timer.h
+++ b/include/kernel/timer.h
@@ -44,6 +44,12 @@
void *arg;
} timer_t;
+/* Rules for Timers:
+ * - Timer callbacks occur from interrupt context
+ * - Timers may be programmed or canceled from interrupt or thread context
+ * - Timers may be canceled or reprogrammed from within their callback
+ * - Timers currently are dispatched from a 10ms periodic tick
+*/
void timer_initialize(timer_t *);
void timer_set_oneshot(timer_t *, time_t delay, timer_callback, void *arg);
void timer_set_periodic(timer_t *, time_t period, timer_callback, void *arg);