1 files changed, 70 insertions, 15 deletions

diff --git a/include/timer.h b/include/timer.h
index 0a4273ff25..b13e0a62a0 100644
--- a/include/timer.h
+++ b/include/timer.h
@@ -11,6 +11,12 @@
 #include "common.h"
 #include "task_id.h"
 
+/* Time units in microseconds */
+#define MSEC         1000
+#define SECOND    1000000
+#define MINUTE   60000000
+#define HOUR   3600000000ull  /* Too big to fit in a signed int */
+
 /* Microsecond timestamp. */
 typedef union {
 	uint64_t val;
@@ -20,15 +26,27 @@ typedef union {
 	} le /* little endian words */;
 } timestamp_t;
 
-/* Initializes the Timer module. */
-int timer_init(void);
+/**
+ * Initialize the timer module.
+ */
+void timer_init(void);
 
-/* Launch a one-shot timer for task <tskid> which expires at timestamp
- * <tstamp>. */
+/**
+ * Launch a one-shot timer for a task.
+ *
+ * Note that each task can have only a single active timer.
+ *
+ * @param tstamp	Expiration timestamp for timer
+ * @param tskid		Task to set timer for
+ *
+ * @return EC_SUCCESS, or non-zero if error.
+ */
 int timer_arm(timestamp_t tstamp, task_id_t tskid);
 
-/* Cancel a running timer for the specified task id. */
-int timer_cancel(task_id_t tskid);
+/**
+ * Cancel a running timer for the specified task id.
+ */
+void timer_cancel(task_id_t tskid);
 
 /**
  * Check if a timestamp has passed / expired
@@ -39,30 +57,67 @@ int timer_cancel(task_id_t tskid);
  */
 int timestamp_expired(timestamp_t deadline, const timestamp_t *now);
 
-/* Busy-wait the selected number of microseconds.  Note that calling this
- * with us>1000 may impact system performance; use usleep for longer delays. */
+/**
+ * Busy-wait.
+ *
+ * Note that calling this with us>1000 may impact system performance; use
+ * usleep() for longer delays.
+ *
+ * @param us		Number of microseconds to delay.
+ */
 void udelay(unsigned us);
 
-/* Sleep during the selected number of microseconds.  The current task will be
- * de-scheduled until the delay expires.
+/**
+ * Sleep.
+ *
+ * The current task will be de-scheduled for at least the specified delay (and
+ * perhaps longer, if a higher-priority task is running when the delay
+ * expires).
  *
- * Note: if an event happens before the end of sleep, the function will return.
+ * @param us		Number of microseconds to sleep.
  */
 void usleep(unsigned us);
 
-/* Get the current timestamp from the system timer. */
+/**
+ * Sleep for milliseconds
+ *
+ * @param ms		Number of milliseconds to sleep.
+ */
+static inline void msleep(unsigned ms)
+{
+	usleep(ms * MSEC);
+}
+
+/**
+ * Sleep for seconds
+ *
+ * @param sec		Number of seconds to sleep.
+ */
+static inline void sleep(unsigned sec)
+{
+	usleep(sec * SECOND);
+}
+
+/**
+ * Get the current timestamp from the system timer.
+ */
 timestamp_t get_time(void);
 
-/* Force the current value of the system timer.
+/**
+ * Force the current value of the system timer.
  *
  * This function is for the power management implementation which wants to fix
  * the system time when waking up from a mode with clocks turned off.
+ *
  * Note: must be called with interrupts disabled.
  */
 void force_time(timestamp_t ts);
 
-/* Print the current timer information using the command output channel.  This
- * may be called from interrupt level. */
+/**
+ * Print the current timer information using the command output channel.
+ *
+ * This may be called from interrupt level.
+ */
 void timer_print_info(void);
 
 /**