From 62fc51338d7259c2ea39f38bd8c7d9552e9b2002 Mon Sep 17 00:00:00 2001
From: Kimplul <kimi.h.kuparinen@gmail.com>
Date: Sun, 12 Jun 2022 16:18:47 +0300
Subject: doxygen shows no warnings

+ Does not mean documentation is done, but it's a nice little
  achievement nonetheless.
---
 common/uapi/timers.c | 58 ++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 50 insertions(+), 8 deletions(-)

(limited to 'common/uapi/timers.c')

diff --git a/common/uapi/timers.c b/common/uapi/timers.c
index bc3ef59..b6f9b95 100644
--- a/common/uapi/timers.c
+++ b/common/uapi/timers.c
@@ -9,39 +9,81 @@
 #include <apos/timer.h>
 #include <apos/uapi.h>
 
-static ticks_t scaled_ticks(sys_arg_t ticks, sys_arg_t repeat)
+/**
+ * Convert arch-specific register values \c ticks and \c repeat to \c ticks_t.
+ *
+ * If we're on a 32bit system, one register can't contain a tick value,
+ * so we use two registers and combine them into one value and let the compiler
+ * handle the rest.
+ *
+ * @param ticks Register width tick value.
+ * @param mult Register width repeat value.
+ * @return Corresponding \c ticks_t value.
+ */
+static ticks_t scaled_ticks(sys_arg_t ticks, sys_arg_t mult)
 {
-#if __WORDSIZE == 64
-	UNUSED(repeat);
+#if defined(_LP64)
+	UNUSED(mult);
 	return ticks;
 #else
-	return ((ticks_t)ticks << 32) + repeat;
+	return (ticks_t)ticks * (ticks_t)mult;
 #endif
 }
 
+/**
+ * Timebase syscall handler.
+ *
+ * @return \ref OK and resolution of system timer in Hz.
+ */
 SYSCALL_DEFINE0(timebase)()
 {
 	return (struct sys_ret){ OK, secs_to_ticks(1) };
 }
 
-SYSCALL_DEFINE2(req_rel_timer)(sys_arg_t ticks, sys_arg_t repeat)
+/**
+ * Relative timer request syscall handler.
+ *
+ * \note On 64bit systems, \c repeat is ignored as \c ticks register is large
+ * enough to contain essentially any timepoint we want. A couple thousand years
+ * when the clock runs at 5GHz, if I'm not completely mistaken.
+ *
+ * @param ticks Number of ticks from now.
+ * @param mult Multiply \c ticks by this value.
+ * @return \ref OK and \c cid of created timer.
+ */
+SYSCALL_DEFINE2(req_rel_timer)(sys_arg_t ticks, sys_arg_t mult)
 {
 	return (struct sys_ret){
 		       OK,
 		       new_rel_timer(cur_tcb()->tid,
-		                     scaled_ticks(ticks, repeat))
+		                     scaled_ticks(ticks, mult))
 	};
 }
 
-SYSCALL_DEFINE2(req_abs_timer)(sys_arg_t ticks, sys_arg_t repeat)
+/**
+ * Absolute timer request syscall handler.
+ *
+ * @param ticks Absolute timepoint relative to some start point defined at boot.
+ * @param mult Multiply \c ticks by this value.
+ * @return \ref OK and \c cid of created timer.
+ * \see req_rel_timer().
+ */
+SYSCALL_DEFINE2(req_abs_timer)(sys_arg_t ticks, sys_arg_t mult)
 {
 	return (struct sys_ret){
 		       OK,
 		       new_abs_timer(cur_tcb()->tid,
-		                     scaled_ticks(ticks, repeat))
+		                     scaled_ticks(ticks, mult))
 	};
 }
 
+/**
+ * Free timer request syscall handler.
+ *
+ * @param cid \c cid of timer to free.
+ * @return \ref ERR_NF and \c 0if no timer could be found with \c cid, \ref OK
+ * and 0 otherwise.
+ */
 SYSCALL_DEFINE1(free_timer)(sys_arg_t cid)
 {
 	struct timer *timer = find_timer(cid);
-- 
cgit v1.3