KallistiOS  2.0.0
timer.h
Go to the documentation of this file.
1 /* KallistiOS 2.0.0
2
3  arch/dreamcast/include/timer.h
4  (c)2000-2001 Dan Potter
5
6 */
7
8 /** \file arch/timer.h
9  \brief Low-level timer functionality.
10
11  This file contains functions for interacting with the timer sources on the
12  SH4. Many of these functions may interfere with thread operation or other
13  such things, and should thus be used with caution. Basically, the only
14  functionality that you might use in practice in here in normal programs is
15  the gettime functions.
16
17  \author Dan Potter
18 */
19
20 #ifndef __ARCH_TIMER_H
21 #define __ARCH_TIMER_H
22
23 #include <sys/cdefs.h>
24 __BEGIN_DECLS
25
26 #include <arch/types.h>
27 #include <arch/irq.h>
28
29 /* Timer sources -- we get four on the SH4 */
30
31 /** \brief SH4 Timer 0.
32
33  This timer is used for thread operation, and thus is off limits if you want
34  that to work properly.
35 */
36 #define TMU0 0
37
38 /** \brief SH4 Timer 1.
39
40  This timer is used for the timer_spin_sleep() function.
41 */
42 #define TMU1 1
43
44 /** \brief SH4 Timer 2.
45
46  This timer is used by the various gettime functions in this header.
47 */
48 #define TMU2 2
49
50 /** \brief SH4 Watchdog Timer.
51
52  KallistiOS does not currently support using this timer.
53 */
54 #define WDT 3
55
56 /** \brief Which timer does the thread system use? */
57 #define TIMER_ID TMU0
58
59 /** \brief Pre-initialize a timer, but do not start it.
60
61  This function sets up a timer for use, but does not start it.
62
63  \param which The timer to set up (i.e, \ref TMU0).
64  \param speed The number of ticks per second.
65  \param interrupts Set to 1 to receive interrupts when the timer ticks.
66  \retval 0 On success.
67 */
68 int timer_prime(int which, uint32 speed, int interrupts);
69
70 /** \brief Start a timer.
71
72  This function starts a timer that has been initialized with timer_prime(),
73  starting raising interrupts if applicable.
74
75  \param which The timer to start (i.e, \ref TMU0).
76  \retval 0 On success.
77 */
78 int timer_start(int which);
79
80 /** \brief Stop a timer.
81
82  This function stops a timer that was started with timer_start(), and as a
83  result stops interrupts coming in from the timer.
84
85  \param which The timer to stop (i.e, \ref TMU0).
86  \retval 0 On success.
87 */
88 int timer_stop(int which);
89
90 /** \brief Obtain the count of a timer.
91
92  This function simply returns the count of the timer.
93
94  \param which The timer to inspect (i.e, \ref TMU0).
95  \return The timer's count.
96 */
97 uint32 timer_count(int which);
98
99 /** \brief Clear the underflow bit of a timer.
100
101  This function clears the underflow bit of a timer if it was set.
102
103  \param which The timer to inspect (i.e, \ref TMU0).
104  \retval 0 If the underflow bit was clear (prior to calling).
105  \retval 1 If the underflow bit was set (prior to calling).
106 */
107 int timer_clear(int which);
108
109 /** \brief Spin-loop sleep function.
110
111  This function is meant as a very accurate delay function, even if threading
112  and interrupts are disabled. It uses \ref TMU1 to sleep.
113
114  \param ms The number of milliseconds to sleep.
115 */
116 void timer_spin_sleep(int ms);
117
118 /** \brief Enable high-priority timer interrupts.
119
120  This function enables interrupts on the specified timer.
121
122  \param which The timer to enable interrupts on (i.e, \ref TMU0).
123 */
124 void timer_enable_ints(int which);
125
126 /** \brief Disable timer interrupts.
127
128  This function disables interrupts on the specified timer.
129
130  \param which The timer to disable interrupts on (i.e, \ref TMU0).
131 */
132 void timer_disable_ints(int which);
133
134 /** \brief Check whether interrupts are enabled on a timer.
135
136  This function checks whether or not interrupts are enabled on the specified
137  timer.
138
139  \param which The timer to inspect (i.e, \ref TMU0).
140  \retval 0 If interrupts are disabled on the timer.
141  \retval 1 If interrupts are enabled on the timer.
142 */
143 int timer_ints_enabled(int which);
144
145 /** \brief Enable the millisecond timer.
146
147  This function enables the timer used for the gettime functions. This is on
148  by default. These functions use \ref TMU2 to do their work.
149 */
150 void timer_ms_enable();
151
152 /** \brief Disable the millisecond timer.
153
154  This function disables the timer used for the gettime functions. Generally,
155  you will not want to do this, unless you have some need to use the timer
156  \ref TMU2 for something else.
157 */
158 void timer_ms_disable();
159
160 /** \brief Get the current uptime of the system.
161
162  This function retrieves the number of seconds and milliseconds since KOS was
163  started.
164
165  \param secs A pointer to store the number of seconds since boot
166  into.
167  \param msecs A pointer to store the number of milliseconds past
168  a second since boot.
169  \note To get the total number of milliseconds since boot,
170  calculate (*secs * 1000) + *msecs, or use the
171  timer_ms_gettime64() function.
172 */
173 void timer_ms_gettime(uint32 *secs, uint32 *msecs);
174
175 /** \brief Get the current uptime of the system (in milliseconds).
176
177  This function retrieves the number of milliseconds since KOS was started. It
178  is equivalent to calling timer_ms_gettime() and combining the number of
179  seconds and milliseconds into one 64-bit value.
180
181  \return The number of milliseconds since KOS started.
182 */
184
185 /** \brief Get the current uptime of the system (in microseconds).
186
187  This function retrieves the number of microseconds since KOS was started. It
188  should be more precise, in theory, than timer_ms_gettime64(), but the exact
189  amount of preciseness is undetermined.
190
191  \return The number of microseconds since KOS started.
192 */
194
195 /** \brief Primary timer callback type. */
197
198 /** \brief Set the primary timer callback.
199
200  This function sets the primary timer callback to the specified function
201  pointer. Generally, you should not do this, as the threading system relies
202  on the primary timer to work.
203
204  \param callback The new timer callback (set to NULL to disable).
205  \return The old timer callback.
206 */
208
209 /** \brief Request a primary timer wakeup.
210
211  This function will wake the caller (by calling the primary timer callback)
212  in approximately the number of milliseconds specified. You can only have one
213  timer wakeup scheduled at a time. Any subsequently scheduled wakeups will
214  replace any existing one.
215
216  \param millis The number of milliseconds to schedule for.
217 */
218 void timer_primary_wakeup(uint32 millis);
219
220 /* \cond */
221 /* Init function */
222 int timer_init();
223
224 /* Shutdown */
225 void timer_shutdown();
226 /* \endcond */
227
228 __END_DECLS
229
230 #endif /* __ARCH_TIMER_H */
231