[bug #59884] _delay_ms() documentation wrongly states delay can end up as 0 ms in certain situation

[avrs-admin]

Sat 16 Jan 2021 12:33:02 AM CET

On a 16 MHz Arduino Mega 256, this code:

__builtin_avr_delay_cycles (100.0);   // Compiles, so we apparently have it
debug_led_on ();
_delay_ms (290000.0);
debug_led_off ();
assert (0);

leaves the debug led on for about 269 s.  Same for larger arguments to _delay_ms (e.g. 350000.0).  This is different from what this documentation implies will happen:

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, overflows results in no delay i.e., 0ms.

A discussion on the avr-libc mailing list made clear that the problem is that the documented behavior depends on undefined behavior as described here:

https://lists.nongnu.org/archive/html/avr-libc-dev/2020-01/msg00009.html

Rather than document the particular behavior I would change the documentation for _delay_ms() (at least, not sure if _delay_us() or others might also need attention) to state the behavior in that circumstance is undefined ("propagate" the undefined).

This issue was migrated from https://savannah.nongnu.org/bugs/?59884