start writing documentation

2 files changed, 89 insertions, 8 deletions

diff --git a/include/apos/lock.h b/include/apos/lock.h
index 2fac160..f874399 100644
--- a/include/apos/lock.h
+++ b/include/apos/lock.h
@@ -3,16 +3,31 @@
 
 /**
  * @file lock.h
- * Atomic locks, currently only \ref spin_lock and \ref spin_unlock. Mutex is
+ * Atomic locks, currently only \ref spin_lock() and \ref spin_unlock(). Mutex is
  * probably overkill for this project.
  */
 
 #include <apos/atomic.h>
 #include <apos/irq.h>
+
+/**
+ * Typedef for atomic_int.
+ *
+ * In apos, spinlocks are implemented with compiler-intrinsic atomic integers,
+ * that essentially just contain some flags. Currently all spinlocks
+ * enable/disable irqs.
+ *
+ * \todo irq contexts?
+ */
 typedef atomic_int spinlock_t;
 
-#include <lock.h>
+#include <arch/lock.h>
 
+/**
+ * Lock a spinlock.
+ *
+ * @param lck Pointer to lock.
+ */
 static inline void spin_lock(spinlock_t *lck)
 {
 	disable_irq();
@@ -23,6 +38,11 @@ static inline void spin_lock(spinlock_t *lck)
 	} while (atomic_exchange_explicit(lck, 1, memory_order_acq_rel));
 }
 
+/**
+ * Unlock a spinlock.
+ *
+ * @param lck Pointer to lock.
+ */
 static inline void spin_unlock(spinlock_t *lck)
 {
 	atomic_store_explicit(lck, 0, memory_order_release);
diff --git a/include/apos/timer.h b/include/apos/timer.h
index 85cd5bc..b21a182 100644
--- a/include/apos/timer.h
+++ b/include/apos/timer.h
@@ -4,21 +4,38 @@
 /**
  * @file timer.h
  * Timer handling.
+ *
+ * \todo Document exceptions and return values better.
  */
 
 #include <apos/types.h>
 
-/* GCC will compile uint64_t even on 32bit platforms, just with some runtime
+/**
+ * ticks_t typedef, use unsigned 64bit integer on all platforms.
+ *
+ * GCC will compile uint64_t even on 32bit platforms, just with some runtime
  * overhead, should be fine. This will allow us to have a reasonable time range
- * even with nanosecond clocks. (138 years with ~4.2 Hz clock) */
+ * even with nanosecond clocks. (138 years with ~4.2 Hz clock)
+ */
 typedef uint64_t ticks_t;
-/* whichever time unit we're dealing with */
+
+
+/**
+ * tunit_t typedef, whichever time unit we're dealing with.
+ */
 typedef size_t tunit_t;
 
+/**
+ * Timer structure.
+ */
 struct timer {
+	/** tid. Thread ID of whoever scheduled the timer. */
 	id_t tid;
+	/** cid. Control ID, used to differentiate timers. */
 	id_t cid;
 
+	/** ticks. Absolute number of ticks, essentially a timepoint for when
+	 * the timer should trigger. */
 	ticks_t ticks;
 };
 
@@ -47,26 +64,70 @@ id_t new_rel_timer(id_t tid, ticks_t ticks);
  */
 id_t new_abs_timer(id_t tid, ticks_t ticks);
 
+/**
+ * Return a pointer to the newest timer, i.e. the one that is closest to
+ * triggering.
+ *
+ * @return Pointer to a timer or NULL if queue is empty.
+ */
 struct timer *newest_timer();
+
+/**
+ * Find a timer associated with a specific control ID.
+ *
+ * @param cid Control ID to find.
+ * @return Pointer to associated timer if found, else NULL.
+ */
 struct timer *find_timer(id_t cid);
-void remove_timer(struct timer *);
 
+/**
+ * Remove a timer.
+ *
+ * @param timer Pointer to timer to remove.
+ * @return OK on success.
+ */
+stat_t remove_timer(struct timer *timer);
+
+/**
+ * Convert nanoseconds to ticks.
+ *
+ * @param nsecs Number of nanoseconds to represent as ticks.
+ * @return Equivalent ticks to nsecs.
+ */
 ticks_t nsecs_to_ticks(tunit_t nsecs);
 
+/**
+ * Convert microseconds to ticks.
+ *
+ * @param usecs Number of microseconds to represent as ticks.
+ * @return Equivalent ticks to usecs.
+ */
 static inline ticks_t usecs_to_ticks(tunit_t usecs)
 {
 	return nsecs_to_ticks(usecs * 1000);
 }
 
+/**
+ * Convert milliseconds to ticks.
+ *
+ * @param msecs Number of milliseconds to represent as ticks.
+ * @return Equivalent ticks to msecs.
+ */
 static inline ticks_t msecs_to_ticks(tunit_t msecs)
 {
 	return usecs_to_ticks(msecs * 1000);
 }
 
-/* TODO: likely not a problem on 64bit systems, not sure how to handle situation on
- * 32bit */
+/**
+ * Convert seconds to ticks.
+ *
+ * @param secs Number of seconds to represent as ticks.
+ * @return Equivalent ticks to secs.
+ */
 static inline ticks_t secs_to_ticks(tunit_t secs)
 {
+	/* TODO: likely not a problem on 64bit systems, not sure how to handle situation on
+	 * 32bit */
 	return msecs_to_ticks(secs * 1000);
 }