From 2880b9ff657559b9ce1ab62881b6b4a024822157 Mon Sep 17 00:00:00 2001
From: lillo <lillo@nowhere.fake>
Date: Sat, 20 Jul 2002 22:53:23 +0000
Subject: [PATCH] beos compatible timer routines and style cleanups in timer
 and sem code; also doxygened timer.h

git-svn-id: file:///srv/svn/repos/haiku/trunk/current@354 a95241bf-73f2-0310-859d-f6bbb57e9c96
---
 headers/private/kernel/cpu.h   |   2 +-
 headers/private/kernel/timer.h | 103 ++++++++++++++++++++++++---------
 2 files changed, 77 insertions(+), 28 deletions(-)

diff --git a/headers/private/kernel/cpu.h b/headers/private/kernel/cpu.h
index 419ea10202..11fe1e76cf 100644
--- a/headers/private/kernel/cpu.h
+++ b/headers/private/kernel/cpu.h
@@ -36,7 +36,7 @@ typedef union cpu_ent {
 		/** If set this will force a reschedule when the quantum timer expires */
 		int preempted;
 		/** Quantum timer */
-		struct timer_event quantum_timer;
+		timer quantum_timer;
 	} info;
 	/** Alignment bytes */
 	uint32 align[16];
diff --git a/headers/private/kernel/timer.h b/headers/private/kernel/timer.h
index 891037038c..5f4f08df1d 100755
--- a/headers/private/kernel/timer.h
+++ b/headers/private/kernel/timer.h
@@ -1,43 +1,92 @@
-/* 
-** Copyright 2001-2002, Travis Geiselbrecht. All rights reserved.
-** Distributed under the terms of the NewOS License.
-*/
 #ifndef _KERNEL_TIMER_H
 #define _KERNEL_TIMER_H
 
+/**
+ * @file kernel/timer.h
+ * @brief Timer structures and definitions
+ */
+
 #include <stage2.h>
 
-typedef int (*timer_callback)(void *);
+/**
+ * @defgroup Timer Timer structures (not architecture specific)
+ * @ingroup OpenBeOS_Kernel
+ * @{
+ */
 
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
 
-typedef enum {
-	TIMER_MODE_ONESHOT = 0,
-	TIMER_MODE_PERIODIC
-} timer_mode;
+typedef struct timer timer;
+typedef struct qent	qent;
+typedef	int32 (*timer_hook)(timer *);
 
-struct timer_event {
-	struct timer_event *next;
-	timer_mode mode;
-	bigtime_t sched_time;
-	bigtime_t periodic_time;
-	timer_callback func;
-	void *data;
+/**
+ * qent structure
+ */
+/**
+ * The BeOS qent structure is probably part of a general double linked list
+ * interface used all over the kernel; a struct is required to have a qent
+ * entry struct as first element, so it can be linked to other elements
+ * easily. The key field is probably just an id, eventually used to order
+ * the list.
+ * Since we don't use this kind of interface, but we have to provide it
+ * to keep compatibility, we can use the qent struct for other purposes...
+ */
+struct qent {
+	int64		key;			/* We use this as the sched time */
+	qent		*next;			/* This is used as a pointer to next timer */
+	qent		*prev;			/* This can be used for callback args */
 };
 
-void timer_setup_timer(timer_callback func, void *data, struct timer_event *event);
-int timer_set_event(bigtime_t relative_time, timer_mode mode, struct timer_event *event);
-int timer_cancel_event(struct timer_event *event);
-void spin(bigtime_t microseconds);
+/**
+ * Timer event data structure
+ */
+struct timer {
+	/** qent entry for this timer event */
+	qent			entry;
+	/** This just holds the timer operating mode (relative/absolute/periodic) */
+	uint16			flags;
+	/** Number of the CPU associated to this timer event */
+	uint16			cpu;
+	/** Hook function to be called on timer expiration */
+	timer_hook		hook;
+	/** Expiration time in microseconds */
+	bigtime_t		period;
+};
 
-/* kernel functions */
+/** @defgroup timermodes Timer operating modes
+ *  @ingroup Timer
+ *  @{
+ */
+/** @def B_ONE_SHOT_ABSOLUTE_TIMER the timer will fire once at the system
+ *  time specified by period
+ */
+/** @def B_ONE_SHOT_RELATIVE_TIMER the timer will fire once in approximately
+ *  period microseconds
+ */
+/** @def B_PERIODIC_TIMER the timer will fire every period microseconds,
+ *  starting in period microseconds
+ */
+#define		B_ONE_SHOT_ABSOLUTE_TIMER		1
+#define		B_ONE_SHOT_RELATIVE_TIMER		2
+#define		B_PERIODIC_TIMER				3
+/** @} */
+
+status_t  add_timer(timer *event, timer_hook hook, bigtime_t period, int32 flags);
+bool      cancel_timer(timer *event);
+void      spin(bigtime_t microseconds);
+
+/** kernel functions */
 int  timer_init(kernel_args *);
 int  timer_interrupt(void);
 
-/*
- * these two are only to be used by the scheduler
- */
-int local_timer_cancel_event(struct timer_event *event);
-int _local_timer_cancel_event(int curr_cpu, struct timer_event *event);
+/** these two are only to be used by the scheduler */
+int local_timer_cancel_event(timer *event);
+int _local_timer_cancel_event(int curr_cpu, timer *event);
 
-#endif
+/** @} */
+
+#endif /* _KERNEL_TIMER_H */