<util/delay.h>: Convenience functions for busy-wait delay loops

Macros
#define	F_CPU   1000000UL

Functions
static void	_delay_ms (double __ms)
static void	_delay_us (double __us)

Detailed Description

#define F_CPU 1000000UL  // 1 MHz
//#define F_CPU 14.7456e6
#include <util/delay.h>

The functions in this header are meant as convenience functions where actual time values can be specified as a delay time, rather than a number of cycles to wait for.

This requires that the clock frequency of the device is provided in the F_CPU macro in units of Hertz. The macro must be defined before including the <util/delay.h> header. It can be defined in the source code like indicated above, or it can be defined on the command line / in a Makefile by means of -D F_CPU=...

The functions in this header file are wrappers around the basic busy-wait functions from <util/delay_basic.h>, or, when supported by the compiler, then __builtin_avr_delay_cycles() is used instead.

In any case, the delay functions provided by this header will not disable interrupts, which means hat the delay time will be longer than specified when interrupts occur while a delay function is running.

In order for these functions to work as intended, compiler optimizations must be enabled, and the delay time must be an expression that is a known constant at compile-time. If these requirements are not met, the resulting delay will be much longer (and basically unpredictable), and applications that otherwise do not use floating-point calculations will experience severe code bloat by the floating-point library routines linked into the application. The idea is that compile-time constant expressions will be eliminated by compiler optimization so floating-point expressions can be used to calculate the number of delay cycles needed based on the CPU frequency passed by the macro F_CPU.

The functions available allow the specification of microsecond, and millisecond delays directly, using the application-supplied macro F_CPU as the CPU clock frequency in Hertz.

Macro Definition Documentation

F_CPU

#define F_CPU   1000000UL

CPU frequency in Hz.

The macro F_CPU specifies the CPU frequency in Hertz to be considered by the delay functions. This macro is normally supplied by the environment (e.g. from within a project header, or the project's Makefile). The value 1 MHz here is only provided as a fallback default if no such user-provided definition could be found.

In terms of the delay functions, the CPU frequency can be given as a floating-point constant (e.g. 3.6864e6 for 3.6864 MHz). However, the macros in <util/setbaud.h> require it to be an integer value.

Function Documentation

_delay_ms()

static void _delay_ms ( double  __ms )

inlinestatic

Perform a delay of __ms milliseconds.

The macro F_CPU is supposed to be defined to a constant defining the CPU clock frequency in Hertz.

• If __builtin_avr_delay_cycles() is supported by the compiler, then the maximal possible delay is 4294967.04 / f_CPU milliseconds where f_CPU denotes the CPU frequency in units of 1 MHz. This is around 71 minutes / f_CPU. Values greater than that are saturated to this value.
• Otherwise, _delay_loop_2() is used as a fallback, and the maximal possible delay is 262.14 / f_CPU milliseconds. When the user requests a delay which exceeds the maximum possible one, _delay_ms() provides a decreased resolution functionality. In this mode _delay_ms() will work with a resolution of 1/10 ms, providing delays up to 6.5535 seconds (independent from CPU frequency). The user will not be informed about decreased resolution.

Conversion of __ms into clock cycles may not always result in an integral value. By default, the clock cycles are rounded up to the next integer. This ensures that the user gets at least __ms microseconds of delay. Alternatively, by defining the macro __DELAY_ROUND_DOWN__, or __DELAY_ROUND_CLOSEST__, before including this header file, the algorithm can be made to round down, or round to closest integer, respectively.

Note

The implementation of _delay_ms() based on __builtin_avr_delay_cycles() is not backward compatible with older implementations. In order to get a functionality backward compatible with previous versions, the macro __DELAY_BACKWARD_COMPATIBLE__ must be defined before including this header file.

_delay_us()

static void _delay_us ( double  __us )

inlinestatic

Perform a delay of __us microseconds.

The macro F_CPU is supposed to be defined to a constant defining the CPU clock frequency in Hertz.

• If __builtin_avr_delay_cycles() is supported by the compiler, then the maximal possible delay is 4294967040 / f_CPU microseconds where f_CPU denotes the CPU frequency in units of 1 MHz. This is around 71 minutes / f_CPU. Values greater than that are saturated to this value.
• Otherwise, _delay_loop_1() is used as a fallback, and the maximal possible delay is 768 / f_CPU microseconds. If the user requests a delay greater than the maximal possible one, _delay_us() will automatically call _delay_ms() instead. The user will not be informed about this case.

Conversion of __us into clock cycles may not always result in an integral value. By default, the clock cycles are rounded up to next integer. This ensures that the user gets at least __us microseconds of delay. Alternatively, by defining the macro __DELAY_ROUND_DOWN__, or __DELAY_ROUND_CLOSEST__, before including this header file, the algorithm can be made to round down, or round to closest integer, respectively.

Note

The implementation of _delay_us() based on __builtin_avr_delay_cycles() is not backward compatible with older implementations. In order to get a functionality backward compatible with previous versions, the macro __DELAY_BACKWARD_COMPATIBLE__ must be defined before including this header file.