modm API documentation
void modm::delay (std::chrono::nanoseconds ns)
 
void modm::delay_ns (uint32_t ns)
 
void modm::delay (std::chrono::microseconds us)
 
void modm::delay_us (uint32_t us)
 
void modm::delay (std::chrono::milliseconds ms)
 Spin for milliseconds.
 
void modm::delay_ms (uint32_t ms)
 

Detailed Description

lbuild module: modm:architecture:delay

These functions allow you to spin for a short time using only the CPU.

In general it is recommended to use the std::chrono duration types to allow the compiler to choose the optimal implementation for you:

#include <chrono>
constexpr std::chrono::nanoseconds DELAY_TIME{100};
modm::delay(DELAY_TIME);
constexpr std::chrono::microseconds DELAY_TIME2{200};
modm::delay(DELAY_TIME2); // same signature, different implementation

In your code you can also use the std::chrono literals:

using namespace std::chrono_literals;
modm::delay(100ns);
modm::delay(200us);
modm::delay(300ms);

In order to not require wild casting around of values, there are also three overloads for (unsigned) integer values. These are particularly useful for when you do not want to or cannot use chrono literals.

modm::delay_ns(100);
modm::delay_us(200);
modm::delay_ms(300);

Note that these delay functions work at any CPU clock speed, even if changed dynamically at runtime and are available very early in the startup process at hardware-init time.

Limitations

The main limitations are accuracy and length of delay. The only guarantee given to you is to delay for at least the specified time. Note that invocation of interrupts during spinning may add delay too.

Please note that the delay these functions provide is defined as the time from invocation to the time of execution return. Obviously no delay beyond that is considered, which may require you to use shorter delays to compensate for the overhead of your code:

do // GpioA4 toggling takes longer than 500ns because:
{
modm::delay_ns(500); // takes ~500ns
GpioA4::toggle(); // takes a few cycles
} while(1); // jump back to loop also takes a few cycles

You should always prefer Software Timers (see modm:processing:timer) over these blocking delay functions. However, when modm::Clock is not set up yet, or when you need very small delays (for example to bit-bang a protocol), you need to use these delay functions.

For the technical details on the delay implementations you can read "Accurate Micro- and Nanosecond Delay in modm".

Function Documentation

void modm::delay ( std::chrono::microseconds  us)

Spin for microseconds.

Warning
The maximum delay is 1'000'000us = 1 second. Use milliseconds for longer delays.
Note
In debug mode this function may raise "delay.us" if input validation fails.
void modm::delay ( std::chrono::nanoseconds  ns)

Spin for nanoseconds.

Warning
This function is implemented as best-effort and its resolution will be very coarse especially on platforms with very slow clocks.
The maximum delay is 1'000'000ns = 1 millisecond.