hwtimer: Tidy up and clarify some hw_clock comments

From what I can tell the counter has to tick over at the rate of 1MHz.
Update the comments to make that clear.

BUG=chromium:876737
BRANCH=none
TEST= make buildall -j50

Change-Id: Ib04731c10a68c544973b810cf70ce9ffba556b89
Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/1185230

1 files changed, 20 insertions, 3 deletions

diff --git a/include/hwtimer.h b/include/hwtimer.h
index e47ac967da..f1e3ca2dc7 100644
--- a/include/hwtimer.h
+++ b/include/hwtimer.h
@@ -10,7 +10,11 @@
 
 /**
  * Programs when the next timer should fire an interrupt.
- * deadline: timestamp of the event.
+ *
+ * The deadline is ahead of the current counter (which may of course wrap) by
+ * the number of microseconds until the interrupt should fire.
+ *
+ * @param deadline	timestamp of the event in microseconds
  */
 void __hw_clock_event_set(uint32_t deadline);
 
@@ -20,10 +24,23 @@ uint32_t __hw_clock_event_get(void);
 /* Cancel the next event programed by __hw_clock_event_set */
 void __hw_clock_event_clear(void);
 
-/* Returns the value of the free-running counter used as clock. */
+/**
+ * Get the value of the free-running counter used as clock
+ *
+ * The counter resolution must be 1us, since udelay() relies on this.
+ *
+ * @return current counter value
+ */
 uint32_t __hw_clock_source_read(void);
 
-/* Override the current value of the hardware counter */
+/**
+ * Override the current value of the hardware counter
+ *
+ * The new value takes effect immediately and the counter continues counting
+ * from there, assuming it is enabled
+ *
+ * @ts	Value to write
+ */
 void __hw_clock_source_set(uint32_t ts);
 
 /**