Add README

[rgblamp.git] / tmr.h

diff --git a/tmr.h b/tmr.h
index 716ff65a6d5b68d24f6f937efe5d100811bb74c0..acefa8e1fea31abb922d8281050d0a6d12308f1e 100644 (file)
--- a/tmr.h
+++ b/tmr.h
@@ -1,3 +1,32 @@
+/*
+ * Copyright © 2011, 2012, Titanium Mirror, Inc..
+ * All Rights Reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * - Redistributions of source code must retain the above copyright notice,
+ *   this list of conditions and the following disclaimer.
+ * - Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ * - Neither the name of Titanium Mirror, Inc. nor the names of its
+ *   contributors may be used to endorse or promote products derived from
+ *   this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+ * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+ * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
+ * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
 /*
  * File:   tmr.h
  *
@@ -33,7 +62,6 @@
  * }
  */
 
-
 #ifndef _TMR_H
 #define _TMR_H
 
@@ -41,12 +69,19 @@
 #include "isr.h"
 #include "bit.h"
 
-/* Only access when in ISR or if interrupts are disabled */
+/* Used by 'inline' functions, etc.  User code should not access _tmr_ticks
+ * directly unless interrupts are off; otherwise use tmr_time().
+ */
 extern persistent tmr_time_t _tmr_ticks;
+extern tmr_bitno_t _tmr_on;
+extern tmr_bitno_t _tmr_periodic;
 
 /* Initialize the tmr subsystem */
 void tmr_init();
 
+/* Return non-zero if any timer events are pending */
+#define tmr_events() (_tmr_on)
+
 /* Return non-zero if the timer is on */
 /* FIXME: this may not be atomic WRT ISR */
 #define tmr_on(t) (bit_get(_tmr_on, (t)))
@@ -55,7 +90,7 @@ void tmr_init();
 /* FIXME: this may not be atomic WRT ISR */
 #define tmr_periodic(t) (bit_get(_tmr_periodic, (t)))
 
-/* Start a timer, expecting it to fire in elapsed ticks */
+/* Start a timer, expecting it to fire in elapsed ticks, user code */
 void tmr_start(tmr_bitno_t t, tmr_time_t elapsed);
 
 /* Start a timer, expecting it to fire in elapsed ticks from t0 */
@@ -75,7 +110,7 @@ void tmr_startPeriodicAt(tmr_bitno_t t, tmr_time_t t0, tmr_time_t elapsed);
     nei(); \
   } while(0)
 
-/* Return 1 if the timer has fired, resetting the fired bit */
+/* Return 1 if the timer has fired, resetting the fired bit, user code */
 bit tmr_fired(tmr_bitno_t t);
 
 /* Return the current number of timer ticks, for use outside ISR */
@@ -92,8 +127,8 @@ void tmr_isr();
 /* Wait for c clocks, 0 <= c < 128. */
 #define tmr_cwait(c) \
   do { \
-    unsigned t0 = TMR0; \
-    while ((unsigned)(TMR0 - t0) <= c); /* cast prevents integral promotion */ \
+    unsigned char t0 = TMR0; \
+    while ((unsigned char)(TMR0 - t0) <= c); \
   } while (0)
 
 /* Wait for a number of us.  This is pretty accurate. */