diff --git a/libs/kaptan-spi/Cargo.toml b/libs/kaptan-spi/Cargo.toml new file mode 100644 index 0000000..4261e19 --- /dev/null +++ b/libs/kaptan-spi/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "kaptan-spi" +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true +version.workspace = true + +[lints] +workspace = true diff --git a/libs/kaptan-spi/src/lib.rs b/libs/kaptan-spi/src/lib.rs new file mode 100644 index 0000000..e30f986 --- /dev/null +++ b/libs/kaptan-spi/src/lib.rs @@ -0,0 +1,44 @@ +//! Non-blocking, chip-select-scoped SPI transfer contract. +//! +//! A selected device owns electrical chip-select behavior. A driver retains its +//! transfer storage until a terminal completion event; implementations submit +//! DMA or interrupt-driven work and never wait for a peripheral flag. + +#![no_std] + +/// Terminal outcome reported by a selected SPI device. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum SpiCompletion { + /// The bound interrupt does not report a terminal event. + NotPending, + /// The submitted full-duplex transfer completed. + Complete, + /// The submitted transfer failed and its receive bytes are unusable. + TransferFault, +} + +/// Owns one chip-select-scoped, non-blocking SPI route. +/// +/// `start_transfer` begins a complete transfer and returns without waiting for +/// a peripheral status flag. The caller owns both buffers until the board +/// reports a terminal `SpiCompletion`; `complete_transfer` releases the route +/// after that terminal outcome. +pub trait SpiDevice { + /// Failure to submit a transfer. + type StartError; + + /// Starts one complete full-duplex transfer. + /// + /// Implementations assert chip select before submitting and deassert it on + /// every terminal completion or submission failure. `receive` receives one + /// octet for each `transmit` octet; the two ranges must have equal length. + fn start_transfer( + &mut self, + transmit: &[u8], + receive: &mut [u8], + ) -> Result<(), Self::StartError>; + + /// Releases transport ownership after a hardware ISR acknowledged a + /// terminal completion. This must not poll or wait. + fn complete_transfer(&mut self, completion: SpiCompletion); +}