51 lines
2.1 KiB
Rust
51 lines
2.1 KiB
Rust
//! 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);
|
|
}
|