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