--- name: "util_delay" section: "3avr" platform: "linux" package: "avr-libc" version: "1:2.2.1-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/util_delay" --- # util\_delay(3avr) \: Convenience functions for busy-wait delay loops ## NAME util\_delay - \: Convenience functions for busy-wait delay loops ## SYNOPSIS ### 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 ``` **Note** As an alternative method, it is possible to pass the F\_CPU macro down to the compiler from the Makefile. Obviously, in that case, no `#define` statement should be used. The functions in this header file are wrappers around the basic busy-wait functions from `<`**util/delay\_basic.h**`>`**. They are meant as convenience functions where actual time values can be specified rather than a number of cycles to wait for. The idea behind 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.** **Note** **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 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 ### #define F\_CPU 1000000UL **CPU frequency in Hz. The macro F\_CPU specifies the CPU frequency to be considered by the delay macros. 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 'vanilla' fallback 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 \ require it to be an integer value.** ## Function Documentation ### void \_delay\_ms (double \_\_ms)` [inline]`, ` [static]` **Perform a delay of** `__ms` **milliseconds, using \_delay\_loop\_2().** **The macro F\_CPU is supposed to be defined to a constant defining the CPU clock frequency (in Hertz).** **The maximal possible delay is 262.14 ms / F\_CPU in MHz.** **When the user request delay which exceed 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.** **If the avr-gcc toolchain has** `__builtin_avr_delay_cycles()` **support, maximal possible delay is 4294967.295 ms/ F\_CPU in MHz. For values greater than the maximal possible delay, overflow may result in no delay i.e., 0 ms.** **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 functionality backward compatible with previous versions, the macro** `__DELAY_BACKWARD_COMPATIBLE__` **must be defined before including this header file.** ### void \_delay\_us (double \_\_us)` [inline]`, ` [static]` **Perform a delay of** `__us` **microseconds, using \_delay\_loop\_1().** **The macro F\_CPU is supposed to be defined to a constant defining the CPU clock frequency (in Hertz).** **The maximal possible delay is 768 s / F\_CPU in MHz.** **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.** **If the avr-gcc toolchain has \_\_builtin\_avr\_delay\_cycles() support, maximal possible delay is 4294967.295 s/ F\_CPU in MHz. For values greater than the maximal possible delay, overflow may result in no delay i.e., 0 s.** **Conversion of** `__us` **into clock cycles may not always result in integer. 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 functionality backward compatible with previous versions, the macro** `__DELAY_BACKWARD_COMPATIBLE__` **must be defined before including this header file.** ## Author **Generated automatically by Doxygen for AVR-LibC from the source code.**