util_delay(3avr)

💖 util_delay(3avr) 💖

okay bestie, gather round, because this is the page for util_delay — the <util/delay.h> header, aka Convenience functions for busy-wait delay loops. it's giving "I just want to wait 5 milliseconds and not do math about clock cycles" energy, and honestly? iconic. ✨

---

🌸 SYNOPSIS 🌸

Macros

#define F_CPU   1000000UL

Functions

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

---

🦋 Detailed Description 🦋

here's the whole vibe, in code:

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

Note 🎀 — bestie, plot twist: you can also just pass the F_CPU macro down to the compiler from the Makefile. but if you do that? then obviously no #define statement should be used. pick a lane, we can't be doing both.

so what are these functions actually doing? they're wrappers around the basic busy-wait functions from <util/delay_basic.h>. the whole point — the main character energy, if you will — is that you get to say "wait this many seconds-ish" instead of "wait this many cycles". and the trick is that compile-time constant expressions get 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. no cap. 🔥

Note ⚠️ — for real for real, 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 those 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 from the floating-point library routines linked into the application. so like. don't.

the functions available let you specify 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, periodt. 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.

and in terms of the delay functions, the CPU frequency can totally be given as a floating-point constant (e.g. 3.6864e6 for 3.6864 MHz) — slay. however, the macros in <util/setbaud.h> require it to be an integer value. so know your audience, bestie.

---

👑 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 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). and the user will not be informed about the decreased resolution. surprise! it's giving ambush but make it embedded.

if the avr-gcc toolchain has __builtin_avr_delay_cycles() support, the 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 milliseconds of delay. generous queen. 👑

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. your delay, your rules. ✨

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. write that down. 📝

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. and the user will not be informed about this case. sneaky little handoff, we love a delegation moment. 🙈

if the avr-gcc toolchain has __builtin_avr_delay_cycles() support, the 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. again: 💀

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. same warning, same energy, don't skip it. 🫶

---

⭐ Author ⭐

Generated automatically by Doxygen for AVR-LibC from the source code. (not me, I just gave it a glow-up 💅)

---

okay that's the whole page! this one lives in AVR-LibC, Version 2.2.1, under the name util_delay(3avr) — so go forth, delay responsibly, keep your optimizations ON, and remember: the compiler does not care about your feelings, only about your compile-time constants. bye bestie, mwah! 💖🌸🦋✨