System Timing and Delay Guide

Overview

The system clock module provides simple delay primitives for timing-dependent operations in embedded applications. These functions are intentionally minimal to work across diverse platform implementations.

Key Concepts

• Millisecond delays (system_delay_ms) for longer timing sequences
• Microsecond delays (system_delay_us) for precise sub-millisecond timing
• Platform-specific implementation for accuracy and power efficiency

Common Use Cases

• Debouncing GPIO inputs
• Timing I2C/SPI transaction sequences
• Adding delays between hardware initialization steps
• Bit-banging protocol timing

Practical Examples

GPIO Debouncing

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

CFBD_Bool read_debounced_button(CFBD_GPIOHandle* button_pin) {
    // Initial read
    CFBD_Bool first_read = CFBD_GPIORead(button_pin);

    // Wait for switch to settle
    system_delay_ms(20);

    // Confirm state hasn't changed
    CFBD_Bool second_read = CFBD_GPIORead(button_pin);
    return (first_read == second_read) ? first_read : CFBD_FALSE;
}

I2C Bus Timing

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

void i2c_bit_banged_start_condition(void) {
    // SDA and SCL high
    set_sda_high();
    set_scl_high();
    system_delay_us(5);

    // Bring SDA low while SCL is high
    set_sda_low();
    system_delay_us(5);

    // Bring SCL low
    set_scl_low();
}

Platform Considerations

• Accuracy: Actual delay may vary depending on system load and interrupt activity
• Interrupt Safety: Check platform documentation for ISR usage restrictions
• Power: Consider sleep/standby modes for longer waits
• Busy-wait: Current implementations typically use busy-wait loops

Best Practices

1. Use millisecond delays for non-critical timing sequences
2. Use microsecond delays only when necessary for precision
3. Avoid calling from interrupt handlers (unless documented as safe)
4. Consider application clock frequency when porting between platforms
5. Combine with hardware timers for more accurate long-duration timing

---

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