//! 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 platform-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);
}