Add pull-up detection and timeout mechanisms to prevent I2C hangs

[Copilot]

Problem

The I2C library could hang forever if pull-up resistors were not present on the SCL and SDA lines. This occurred in functions like wait_for_clock_high() which contained infinite polling loops:

// This would hang forever without pull-ups
unsigned val = peek(p_i2c);
while (!(val & SCL_HIGH)) {
  val = peek(p_i2c);  // Infinite loop if no pull-up
}

Similarly, the async implementation used p_scl when pinseq(1) :> void; which would block indefinitely.

Solution

Implemented comprehensive pull-up detection and timeout mechanisms across all I2C master implementations:

1. Extended Error Codes

Added new error codes to help developers identify missing pull-ups:

typedef enum {
  I2C_NACK,
  I2C_ACK,
  I2C_SCL_PULLUP_MISSING,  // ← New
  I2C_SDA_PULLUP_MISSING,  // ← New
} i2c_res_t;

typedef enum {
  I2C_REGOP_SUCCESS,
  I2C_REGOP_DEVICE_NACK,
  I2C_REGOP_INCOMPLETE,
  I2C_REGOP_SCL_PULLUP_MISSING,  // ← New
  I2C_REGOP_SDA_PULLUP_MISSING,  // ← New
} i2c_regop_res_t;

2. Pull-up Detection at Startup

Each implementation now tests for pull-ups before operations begin:

// Test by driving low then releasing and checking for high within timeout
p_scl <: 0;          // Drive low
delay_ticks(100);    // Brief delay
p_scl :> void;       // Release
// Check if line goes high within 10μs timeout

3. Timeout Mechanisms

Single-port: Added timeout to wait_for_clock_high():

const unsigned timeout_ticks = BIT_TIME(kbits_per_second) * 1000;
// ... timeout checking logic
if (start_time > timeout_time) {
  return I2C_SCL_PULLUP_MISSING;
}

Two-port: Added timeout to release_clock_and_wait():

select {
  case p_scl when pinseq(1) :> void:
    break;  // Success
  case tmr when timerafter(timeout_time) :> void:
    return I2C_SCL_PULLUP_MISSING;  // Timeout
}

Async: Added clock timeout state machine:

case clock_timeout_enabled => tmr when timerafter(clock_timeout_time) :> int now:
  res = I2C_SCL_PULLUP_MISSING;
  // Complete operation with error

4. Usage Example

Applications can now detect and handle missing pull-ups:

i2c_regop_res_t result;
uint8_t value = read_reg(i2c, 0x48, 0x00, result);

switch (result) {
  case I2C_REGOP_SCL_PULLUP_MISSING:
    printf("Error: SCL pull-up resistor missing\n");
    break;
  case I2C_REGOP_SDA_PULLUP_MISSING:
    printf("Error: SDA pull-up resistor missing\n");
    break;
  case I2C_REGOP_SUCCESS:
    printf("Read successful: 0x%02X\n", value);
    break;
}

Benefits

• No more infinite hangs - Library will never freeze due to missing pull-ups
• Clear diagnostics - Specific error codes identify exactly which pull-up is missing
• Backward compatible - Existing code continues to work unchanged
• Comprehensive - All I2C master implementations protected (single-port, two-port, async)
• Minimal overhead - Pull-up detection only happens at startup

This transforms a previously fatal hanging condition into a diagnosable error, significantly improving developer experience and system reliability.

Fixes #97.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[xross]

Rather than checking for pull up present on every usage of p_scl and p_sda simply check at startup and set some error variale

Then check this error viable on write() and read() and dont perform the read/write operations but return the error condition

[Copilot]

Rather than checking for pull up present on every usage of p_scl and p_sda simply check at startup and set some error variale

Then check this error viable on write() and read() and dont perform the...

Implemented your suggestion in commit f7a37fa. Changed approach to:

1. Check for pull-ups once at startup using check_pullups_two_port() / check_pullups() functions
2. Store result in bus_error variable
3. Return error immediately in read/write operations if pull-ups missing
4. Removed all timeout checks from operational functions like release_clock_and_wait() and wait_for_clock_high()

This is much simpler and more efficient than the previous approach. Thank you for the guidance!

[xross]

check_pullups_two_port should only be implemented once in a shared file

[Copilot]

check_pullups_two_port should only be implemented once in a shared file

Implemented in commit 0e14baf. Created i2c_pullup_common.xc and i2c_pullup_common.h to centralize pull-up detection functions. Both check_pullups_two_port and check_pullups_single_port are now shared implementations that can be reused across all I2C master variants.

[xross]

I2C_ACK used to signify something else - an I2S ACK. Its confusing to reuse it for something else here.

[xross]

a single function check_pullups() that takes an array of ports would be better than two whole functions for two and single port.

[xross]

Dont need this comment since we're checking pull ups are present before we call this function

[xross]

Dont need this comment since we're checking pull ups are present before we call this function

[xross]

check both pull ups at start up