From 12be40e22aae582cca9abbd151031edaab800cae Mon Sep 17 00:00:00 2001
From: Kimplul <kimi.h.kuparinen@gmail.com>
Date: Mon, 23 May 2022 23:00:55 +0300
Subject: start writing documentation

---
 include/apos/lock.h | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

(limited to 'include/apos/lock.h')

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);
-- 
cgit v1.3