2004-12-19 Joerg Wunsch
* include/avr/delay.h: Document the inline functions; implement
the macros mentioned in TODO.
* doc/TODO: Delete the respective TODO item.
Index: include/avr/delay.h
===================================================================
RCS file: /cvsroot/avr-libc/avr-libc/include/avr/delay.h,v
retrieving revision 1.5
diff -u -u -r1.5 delay.h
--- include/avr/delay.h 1 Nov 2004 21:19:54 -0000 1.5
+++ include/avr/delay.h 19 Dec 2004 22:36:16 -0000
@@ -39,7 +39,50 @@
#include
-/* 8-bit count, 3 cycles/loop */
+/** \defgroup avr_delay Busy-wait delay loops
+ \code
+ #include
+ \endcode
+
+ The macros in this header file implement simple delay loops
+ that perform a busy-waiting. They are typically used to
+ facilitate short delays in the program execution. They are
+ implemented as count-down loops with a well-known CPU cycle
+ count per loop iteration. As such, no other processing can
+ occur simultaneously. It should be kept in mind that the
+ functions described here do not disable interrupts.
+
+ In general, for long delays, the use of hardware timers is
+ much preferrable, as they free the CPU, and allow for
+ concurrent processing of other events while the timer is
+ running. However, in particular for very short delays, the
+ overhead of setting up a hardware timer is too much compared
+ to the overall delay time.
+
+ Two inline functions are provided for the actual delay
+ algorithms. Two wrapper macros allow the specification of
+ microsecond, and millisecond delays directly, using the
+ application-supplied macro F_CPU as the CPU clock frequency
+ (in Hertz).
+
+ \note While these macros perform all calculation at compile-time
+ using the C preprocessor, so no run-time overhead results, care
+ should be taken to not overflow the argument domain range, as the
+ macros cannot detect such an overflow but would rather truncate
+ the loop count, yielding unintented delay values.
+*/
+
+/** \ingroup avr_delay
+
+ Delay loop using an 8-bit counter \c __count, so up to 256
+ iterations are possible. (The value 256 would have to be passed
+ as 0.) The loop executes three CPU cycles per iteration, not
+ including the overhead the compiler needs to setup the counter
+ register.
+
+ Thus, at a CPU speed of 1 MHz, delays of up to 768 microseconds
+ can be achieved.
+*/
static __inline__ void
_delay_loop_1(uint8_t __count)
{
@@ -51,7 +94,17 @@
);
}
-/* 16-bit count, 4 cycles/loop */
+/** \ingroup avr_delay
+
+ Delay loop using a 16-bit counter \c __count, so up to 65536
+ iterations are possible. (The value 65536 would have to be
+ passed as 0.) The loop executes four CPU cycles per iteration,
+ not including the overhead the compiler requires to setup the
+ counter register pair.
+
+ Thus, at a CPU speed of 1 MHz, delays of up to about 262.1
+ milliseconds can be achieved.
+ */
static __inline__ void
_delay_loop_2(uint16_t __count)
{
@@ -63,8 +116,33 @@
);
}
-/* TODO: macros to allow specifying delays directly in microseconds
- (with MCU clock frequency defined by the user). With constant
- delays, all floating point math would be done at compile time. */
+
+/**
+ \ingroup avr_delay
+ \def _delay_us
+
+ Perform a delay of \c count microseconds, using _delay_loop_1().
+
+ The macro F_CPU is supposed to be defined to an unsigned long
+ integer constant defining the CPU clock frequency (in Hertz).
+
+ The maximal possible delay is 768 us / F_CPU in MHz.
+ */
+#define _delay_us(count) \
+_delay_loop_1((uint8_t)(((unsigned long)(F_CPU) * (count)) / 3000000UL))
+
+/**
+ \ingroup avr_delay
+ \def _delay_ms
+
+ Perform a delay of \c count milliseconds, using _delay_loop_2().
+
+ The macro F_CPU is supposed to be defined to an unsigned long
+ integer constant defining the CPU clock frequency (in Hertz).
+
+ The maximal possible delay is 262.14 ms / F_CPU in MHz.
+ */
+#define _delay_ms(count) \
+_delay_loop_2((uint16_t)(((unsigned long)(F_CPU) * (count)) / 4000UL))
#endif /* _AVR_DELAY_H_ */
Index: doc/TODO
===================================================================
RCS file: /cvsroot/avr-libc/avr-libc/doc/TODO,v
retrieving revision 1.26
diff -u -u -r1.26 TODO
--- doc/TODO 15 Feb 2004 20:25:21 -0000 1.26
+++ doc/TODO 19 Dec 2004 22:39:54 -0000
@@ -6,14 +6,9 @@
* include/avr/twi.h
- Move the following to examples and document
* include/avr/parity.h
- - In include/avr/delay.h, add macros to allow specifying delays directly
- in microseconds (with MCU clock frequency defined by the user). With
- constant delays, all floating point math would be done at compile time.
- A patch has been posted to the avr-libc list, see [6].
- Document:
* include/avr/crc16.h
* include/avr/parity.h
- * include/avr/delay.h (also see above)
* merge chapter 3 from Rich Neswold's doc. Needs some rewriting to
update for newer tools. (explanation of start code)
* gcrt1.S
@@ -41,6 +36,5 @@
[3] http://mail.nongnu.org/archive/html/avr-libc-dev/2002-08/msg00117.html
[4] http://mail.nongnu.org/archive/html/avr-libc-dev/2002-09/msg00038.html
[5] http://mail.nongnu.org/archive/html/avr-libc-dev/2002-12/msg00034.html
-[6] http://mail.nongnu.org/archive/html/avr-libc-dev/2003-01/msg00040.html
[7] http://mail.nongnu.org/archive/html/avr-libc-dev/2003-01/msg00077.html
[8] http://mail.nongnu.org/archive/html/avr-libc-dev/2003-09/msg00030.html