libs/kaptan-i2c: add non-blocking controller contract

libs/kaptan-i2c/src/lib.rs

@@ -0,0 +1,50 @@
+//! Non-blocking I²C transaction contract.
+//!
+//! Controllers own in-flight transfer storage. Implementations may use
+//! interrupts or DMA, but must never make a driver wait for a peripheral
+//! status flag.
+
+#![no_std]
+
+/// Terminal outcome reported by an I²C controller.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum I2cCompletion {
+    /// The bound interrupt had no terminal transaction event.
+    NotPending,
+    /// The submitted transaction completed and read bytes are valid.
+    Complete,
+    /// The submitted transaction failed and read bytes are unusable.
+    TransferFault,
+}
+
+/// Owns a non-blocking I²C controller route and its in-flight storage.
+///
+/// Each operation sends a STOP on successful completion. Controllers copy a
+/// submitted write into owned storage before returning. A completed read is
+/// copied into the caller-provided destination only from
+/// [`Self::complete_transaction`], after the hardware no longer accesses the
+/// controller-owned storage. This avoids retaining pointers to caller slices
+/// across interrupt boundaries.
+pub trait I2cBus {
+    /// Failure to submit a transaction.
+    type StartError;
+
+    /// Starts one address-scoped write transaction ending with a STOP.
+    fn start_write(&mut self, address: u8, write: &[u8]) -> Result<(), Self::StartError>;
+
+    /// Starts one address-scoped read transaction ending with a STOP.
+    fn start_read(&mut self, address: u8, length: usize) -> Result<(), Self::StartError>;
+
+    /// Releases controller ownership after a hardware ISR acknowledged the
+    /// terminal event and, for a successful read, copies into `read`.
+    ///
+    /// This must not poll or wait. `read` must match the length submitted to
+    /// [`Self::start_read`] for the completed read transaction.
+    fn complete_transaction(&mut self, completion: I2cCompletion, read: Option<&mut [u8]>);
+
+    /// Cancels an in-flight transaction after a board-selected timeout.
+    ///
+    /// Implementations must release controller-owned transaction state and
+    /// arrange for any required STOP or peripheral recovery without waiting.
+    fn cancel_transaction(&mut self);
+}