System Clock and Timing¶

Short blocking delay primitives for timing operations. More...

Files¶

Name
lib/application/sys_clock/system_clock.h System timing primitives and delay helpers.

Functions¶

	Name
void	system_delay_ms(uint32_t delay_ms) Delay execution for at least the given number of milliseconds.
void	system_delay_us(uint32_t us) Delay execution for at least the given number of microseconds.

Detailed Description¶

Short blocking delay primitives for timing operations.

Provides minimal, portable timing helpers for embedded systems development. These primitives are intended for short delays in initialization sequences, debouncing, and protocol timing. For longer or more precise timing requirements, consider using hardware timers or dedicated scheduling systems.

Functions Documentation¶

function system_delay_ms¶

void system_delay_ms(
    uint32_t delay_ms
)

Delay execution for at least the given number of milliseconds.

Parameters:

delay_ms Number of milliseconds to delay (>= 0). A value of 0 should return immediately. Values greater than a few seconds should generally be avoided due to busy-wait power consumption.
delay_ms

See: system_delay_us()

Since: 0.1

Note: we must use for loop for delay, as the large decrement makes the slow deviation for the delay

Par:

Thread-safety

The function may or may not be safe to call from interrupt context; check the platform implementation before invoking from ISRs. * Performance Notes

Implementations typically use busy-wait loops or hardware timers. The actual delay may be slightly longer than requested due to instruction execution overhead. * Example

#include "lib/application/sys_clock/system_clock.h"

// Wait 100 ms for a sensor to stabilize
system_delay_ms(100);

// Multiple delays in sequence
for (int i = 0; i < 5; i++) {
    system_delay_ms(500);  // 500 ms between actions
}

Blocks the calling context for approximately delay_ms milliseconds. The actual resolution and maximum accuracy depend on the platform timer implementation. The function is intended for short delays such as debouncing or simple timing sequences. For longer waits or low power idle, prefer platform-specific sleep APIs if available.

Common use cases:

GPIO debouncing (typically 10-50 ms)
Sensor settling time
UI interaction delays
Initialization sequencing

Delay execution for at least the given number of milliseconds.

function system_delay_us¶

void system_delay_us(
    uint32_t us
)

Delay execution for at least the given number of microseconds.

Parameters:

us Number of microseconds to delay (>= 0). A value of 0 should return immediately. Large values (> 1000000) should generally use [system_delay_ms()](Modules/group__Timing__Module.md#function-system-delay-ms) instead.
us

See: system_delay_ms()

Since: 0.1

Par:

Performance

Implementations may use busy-wait loops; avoid calling with large values in performance-sensitive or low-power scenarios. Accuracy may degrade for delays shorter than 10 microseconds depending on platform overhead. * Precision Warning

Timing accuracy depends heavily on:

System clock frequency stability
Instruction execution time
Interrupt latency (if not called from ISR with interrupts disabled) Do not rely on precise timing for critical applications without additional hardware support.
Example

#include "lib/application/sys_clock/system_clock.h"

// Create a small pulse of 5 microseconds
system_delay_us(5);

// Bit-banged I2C start condition timing
set_sda_low();
system_delay_us(2);  // Setup time
set_scl_low();

// Multiple sub-millisecond delays
for (int bit = 0; bit < 8; bit++) {
    transmit_bit(bit);
    system_delay_us(10);  // Inter-bit timing
}

Blocks the calling context for approximately us microseconds. This helper is useful for short, sub-millisecond timing (peripheral timing requirements, bit-banged protocols, etc.). Accuracy and minimum granularity depend on the underlying timer implementation.

The resolution on most platforms is typically 1-10 microseconds, though exact behavior is implementation-defined. For very precise timing, consider using dedicated hardware peripherals.

Common use cases:

I2C/SPI timing sequences
Pulse width generation for bit-banging
Hardware-specific timing requirements
Precise interval measurements below millisecond granularity

Delay execution for at least the given number of microseconds.

Updated on 2026-02-03 at 13:21:55 +0000