| // Licensed under the Apache-2.0 license | |
| // SPDX-License-Identifier: Apache-2.0 | |
| //! # I2C Hardware Abstraction Traits | |
| //! | |
| //! This module defines composable traits for I2C hardware abstraction following | |
| //! a clean separation of concerns. Each trait has a specific responsibility | |
| //! and can be composed to build complete I2C functionality. | |
| //! | |
| //! ## Design Philosophy | |
| //! | |
| //! The traits are designed to be: | |
| //! - **Composable**: Small, focused traits that can be combined | |
| //! - **Flexible**: Different implementations can pick the traits they need | |
| //! - **Extensible**: New functionality can be added without breaking existing code | |
| //! - **Clear**: Each trait has a single, well-defined responsibility | |
| //! | |
| //! ## Trait Hierarchy | |
| //! | |
| //! ```text | |
| //! I2cHardwareCore (foundation) | |
| //! ├── I2cMaster (master operations) | |
| //! └── slave module (blocking operations only) | |
| //! ├── I2cSlaveCore (basic slave setup) | |
| //! ├── I2cSlaveBuffer (data transfer) | |
| //! ├── I2cSlaveInterrupts (interrupt & status management) | |
| //! │ └── I2cSlaveEventSync (sync/blocking events) | |
| //! ├── Composite Traits: | |
| //! │ ├── I2cSlaveBasic (core + buffer) | |
| //! │ └── I2cSlaveSync (basic + sync events) | |
| //! └── I2cMasterSlave (master + sync slave) | |
| //! ``` | |
| //! | |
| //! For non-blocking slave operations, see `openprot-hal-nb::i2c_hardware`. | |
| use embedded_hal::i2c::{AddressMode, ErrorType, Operation, SevenBitAddress}; | |
| /// Core I2C hardware interface providing basic operations | |
| /// | |
| /// This is the foundation trait that all I2C hardware implementations must provide. | |
| /// It contains only the most basic operations needed for any I2C controller. | |
| /// | |
| /// The associated error type comes from [`embedded_hal::i2c::ErrorType`] — the | |
| /// same minimal error-type base embedded-hal itself layers capability traits | |
| /// on (and that `i2c_device::I2CCoreTarget` already uses). Capability traits | |
| /// (`I2cSlaveCore`, …) depend only on `ErrorType`, **not** on this whole | |
| /// init/timing/recover contract. | |
| pub trait I2cHardwareCore: ErrorType { | |
| /// Hardware-specific configuration type for I2C initialization and setup | |
| type Config; | |
| /// I2C speed configuration type | |
| type I2cSpeed; | |
| /// Timing configuration type | |
| type TimingConfig; | |
| /// Initialize the I2C hardware with the given configuration | |
| fn init(&mut self, config: &mut Self::Config) -> Result<(), Self::Error>; | |
| /// Configure timing parameters (clock speed, setup/hold times) | |
| /// | |
| /// Takes timing parameters as input and returns the calculated clock source frequency. | |
| /// This provides type safety by making clear what is read vs. what is computed/returned. | |
| /// | |
| /// # Arguments | |
| /// | |
| /// * `speed` - Target I2C bus speed (Standard, Fast, FastPlus, etc.) | |
| /// * `timing` - Timing configuration parameters for setup/hold times | |
| /// | |
| /// # Returns | |
| /// | |
| /// Returns the actual calculated clock source frequency in Hz. | |
| /// | |
| /// # Errors | |
| /// | |
| /// Returns an error if the requested timing cannot be achieved with the | |
| /// available hardware clock sources or if parameters are invalid. | |
| fn configure_timing( | |
| &mut self, | |
| speed: Self::I2cSpeed, | |
| timing: &Self::TimingConfig, | |
| ) -> Result<u32, Self::Error>; | |
| /// Enable hardware interrupts with the specified mask | |
| fn enable_interrupts(&mut self, mask: u32); | |
| /// Clear hardware interrupts with the specified mask | |
| fn clear_interrupts(&mut self, mask: u32); | |
| /// Handle hardware interrupt events (called from ISR) | |
| fn handle_interrupt(&mut self); | |
| } | |
| /// Bus recovery — minimal seam for callers that need recovery without the full | |
| /// `I2cHardwareCore` init/timing contract. | |
| /// | |
| /// Implemented by hardware drivers that can toggle SCL to un-stick a held-SDA | |
| /// condition. The server-runtime requires this bound so it can recover after | |
| /// bus/arbitration errors without the client needing to know. | |
| pub trait I2cBusRecovery: ErrorType { | |
| /// Attempt to recover the bus from a stuck condition (held SDA/SCL). | |
| /// | |
| /// On success the bus is idle and the next transaction can proceed. | |
| /// On error the bus is unrecoverable by software; the caller should | |
| /// propagate the original transfer error to its client. | |
| fn recover_bus(&mut self) -> Result<(), Self::Error>; | |
| } | |
| /// I2C Master mode operations | |
| /// | |
| /// This trait extends the core interface with master-specific functionality. | |
| /// Implementations provide the actual I2C master protocol operations. | |
| pub trait I2cMaster<A: AddressMode = SevenBitAddress>: I2cHardwareCore { | |
| /// Write data to a slave device at the given address | |
| fn write(&mut self, addr: A, bytes: &[u8]) -> Result<(), Self::Error>; | |
| /// Read data from a slave device at the given address | |
| fn read(&mut self, addr: A, buffer: &mut [u8]) -> Result<(), Self::Error>; | |
| /// Combined write-then-read operation with restart condition | |
| fn write_read(&mut self, addr: A, bytes: &[u8], buffer: &mut [u8]) -> Result<(), Self::Error>; | |
| /// Execute a sequence of I2C operations as a single atomic transaction | |
| fn transaction_slice( | |
| &mut self, | |
| addr: A, | |
| ops_slice: &mut [Operation<'_>], | |
| ) -> Result<(), Self::Error>; | |
| } | |
| /// I2C Slave/Target mode functionality | |
| /// | |
| /// This module contains all slave-related traits decomposed into | |
| /// focused responsibilities for better composability. | |
| pub mod slave { | |
| use super::*; | |
| /// I2C slave events raised by the hardware ISR. | |
| #[derive(Copy, Clone, Debug, PartialEq, Eq)] | |
| pub enum I2cIsrEvent { | |
| /// Master is requesting to read from slave | |
| SlaveRdReq, | |
| /// Master is requesting to write to slave | |
| SlaveWrReq, | |
| /// Slave read operation is in progress | |
| SlaveRdProc, | |
| /// Slave has received write data from master | |
| SlaveWrRecvd, | |
| /// Stop condition received | |
| SlaveStop, | |
| } | |
| /// Status information for I2C slave operations | |
| #[derive(Copy, Clone, Debug, PartialEq, Eq)] | |
| pub struct SlaveStatus { | |
| /// Whether slave mode is currently enabled | |
| pub enabled: bool, | |
| /// Current slave address (if enabled) | |
| pub address: Option<u8>, | |
| /// Whether there's data available to read | |
| pub data_available: bool, | |
| /// Number of bytes in receive buffer | |
| pub rx_buffer_count: usize, | |
| /// Number of bytes in transmit buffer | |
| pub tx_buffer_count: usize, | |
| /// Last slave event that occurred | |
| pub last_event: Option<I2cIsrEvent>, | |
| /// Whether an error condition exists | |
| pub error: bool, | |
| } | |
| /// Core slave functionality - address configuration and mode control | |
| /// | |
| /// This trait provides the fundamental slave operations that all slave | |
| /// implementations need: setting slave address and enabling/disabling slave mode. | |
| /// This is the minimal trait for any I2C slave implementation. | |
| // Slave operation needs only an error type, not the full | |
| // init/timing/recover contract — mirrors embedded-hal's own | |
| // `I2c: ErrorType` layering. (Previously `: super::I2cHardwareCore`, | |
| // which wrongly forced every slave impl to also be a full controller.) | |
| pub trait I2cSlaveCore<A: AddressMode = SevenBitAddress>: super::ErrorType { | |
| /// Configure the slave address for this I2C controller | |
| fn configure_slave_address(&mut self, addr: A) -> Result<(), Self::Error>; | |
| /// Enable slave mode operation | |
| fn enable_slave_mode(&mut self) -> Result<(), Self::Error>; | |
| /// Disable slave mode and return to master-only operation | |
| fn disable_slave_mode(&mut self) -> Result<(), Self::Error>; | |
| /// Check if slave mode is currently enabled | |
| fn is_slave_mode_enabled(&self) -> bool; | |
| /// Get the currently configured slave address | |
| fn slave_address(&self) -> Option<A>; | |
| } | |
| /// Slave buffer operations - data transfer with master | |
| /// | |
| /// This trait handles the actual data exchange between slave and master. | |
| /// Separate from core to allow different buffer management strategies. | |
| /// Implementations can choose different buffering approaches (ring buffer, | |
| /// simple array, DMA, etc.) while maintaining the same interface. | |
| pub trait I2cSlaveBuffer<A: AddressMode = SevenBitAddress>: I2cSlaveCore<A> { | |
| /// Read received data from the slave buffer | |
| /// | |
| /// Returns the number of bytes actually read. The buffer is filled | |
| /// with data received from the master during the last transaction. | |
| /// This is typically called after detecting a slave write event. | |
| fn read_slave_buffer(&mut self, buffer: &mut [u8]) -> Result<usize, Self::Error>; | |
| /// Re-arm the receive path after a drained frame has been consumed. | |
| /// | |
| /// Deferring this call until the consumer has actually taken the data | |
| /// (rather than re-arming right after `read_slave_buffer`) lets | |
| /// hardware that supports clock-stretching hold the bus for exactly as | |
| /// long as the consumer needs, instead of a fixed-size buffer silently | |
| /// overwriting data the consumer hasn't read yet. Implementations | |
| /// without that distinction can leave this a no-op. | |
| fn rearm_slave_receive(&mut self) {} | |
| /// Write response data to the slave transmit buffer | |
| /// | |
| /// Prepares data to be sent to the master during the next read transaction. | |
| /// The data will be transmitted when the master requests it. | |
| fn write_slave_response(&mut self, data: &[u8]) -> Result<(), Self::Error>; | |
| /// Non-blocking check for available slave data | |
| /// | |
| /// Returns Some(length) if data is available to read, None otherwise. | |
| /// This is useful for polling-based implementations or to check | |
| /// before calling read_slave_buffer. | |
| fn poll_slave_data(&mut self) -> Result<Option<usize>, Self::Error>; | |
| /// Clear the slave receive buffer and reset state | |
| /// | |
| /// Clears any pending received data and resets the buffer to | |
| /// a clean state. Useful for error recovery or initialization. | |
| fn clear_slave_buffer(&mut self) -> Result<(), Self::Error>; | |
| /// Get available space in transmit buffer | |
| /// | |
| /// Returns the number of bytes that can be written to the transmit | |
| /// buffer without overflowing. Useful for flow control. | |
| fn tx_buffer_space(&self) -> Result<usize, Self::Error>; | |
| /// Get number of bytes available in receive buffer | |
| /// | |
| /// Returns the current count of bytes waiting to be read from | |
| /// the receive buffer. | |
| fn rx_buffer_count(&self) -> Result<usize, Self::Error>; | |
| } | |
| /// Slave interrupt and status management | |
| /// | |
| /// Common interrupt and status operations shared by both async and sync event patterns. | |
| /// This provides the foundation for event-driven slave operations. | |
| pub trait I2cSlaveInterrupts<A: AddressMode = SevenBitAddress>: I2cSlaveCore<A> { | |
| /// Enable slave-specific hardware interrupts | |
| /// | |
| /// Configures the hardware to generate interrupts for slave events. | |
| /// The mask parameter specifies which interrupt sources to enable. | |
| /// Common interrupts include: address match, data received, stop condition, etc. | |
| fn enable_slave_interrupts(&mut self, mask: u32); | |
| /// Clear slave-specific hardware interrupts | |
| /// | |
| /// Clears pending interrupt flags for the specified interrupt sources. | |
| /// This is typically called in interrupt service routines to acknowledge | |
| /// that the interrupt has been handled. | |
| fn clear_slave_interrupts(&mut self, mask: u32); | |
| /// Current slave hardware status | |
| /// | |
| /// Returns comprehensive status information about the slave controller | |
| /// including enabled state, address, buffer counts, and error conditions. | |
| fn slave_status(&self) -> Result<SlaveStatus, Self::Error>; | |
| /// Last slave event that occurred | |
| /// | |
| /// Returns the most recent slave event, useful for debugging | |
| /// and state tracking. May return None if no events have occurred | |
| /// since reset or if the hardware doesn't track this information. | |
| fn last_slave_event(&self) -> Option<I2cIsrEvent>; | |
| } | |
| /// Blocking slave event handling (sync pattern) | |
| /// | |
| /// This trait provides blocking operations suitable for synchronous code | |
| /// that can afford to wait for events. Operations may block the calling | |
| /// thread until the requested condition is met or timeout occurs. | |
| pub trait I2cSlaveEventSync<A: AddressMode = SevenBitAddress>: I2cSlaveInterrupts<A> { | |
| /// Wait for a specific slave event with timeout | |
| /// | |
| /// Blocks until the specified event occurs or the timeout expires. | |
| /// Returns true if the event occurred, false if timeout expired. | |
| /// Useful for synchronous slave operations that need to coordinate | |
| /// with master transactions. | |
| fn wait_for_slave_event( | |
| &mut self, | |
| expected_event: I2cIsrEvent, | |
| timeout_ms: u32, | |
| ) -> Result<bool, Self::Error>; | |
| /// Wait for any slave event with timeout | |
| /// | |
| /// Blocks until any slave event occurs or timeout expires. | |
| /// Returns the event that occurred, or None if timeout expired. | |
| /// Useful when any event needs to be processed synchronously. | |
| fn wait_for_any_event( | |
| &mut self, | |
| timeout_ms: u32, | |
| ) -> Result<Option<I2cIsrEvent>, Self::Error>; | |
| /// Handle a specific slave event with blocking semantics | |
| /// | |
| /// Processes a slave event and may block if the event handling | |
| /// requires waiting for hardware completion. This is different | |
| /// from the polling version which always returns immediately. | |
| fn handle_slave_event_blocking(&mut self, event: I2cIsrEvent) -> Result<(), Self::Error>; | |
| } | |
| /// Complete slave implementation combining core functionality | |
| /// | |
| /// This trait represents a basic slave implementation that combines | |
| /// core setup and buffer operations. It's suitable for most simple | |
| /// slave use cases without requiring event handling. | |
| pub trait I2cSlaveBasic<A: AddressMode = SevenBitAddress>: | |
| I2cSlaveCore<A> + I2cSlaveBuffer<A> | |
| { | |
| } | |
| /// Blanket implementation: any type implementing core + buffer gets basic slave | |
| impl<T, A: AddressMode> I2cSlaveBasic<A> for T where T: I2cSlaveCore<A> + I2cSlaveBuffer<A> {} | |
| /// Complete sync slave implementation | |
| /// | |
| /// This trait represents a full sync slave implementation that supports | |
| /// all blocking slave operations. Perfect for traditional blocking | |
| /// implementations that can afford to wait. | |
| pub trait I2cSlaveSync<A: AddressMode = SevenBitAddress>: | |
| I2cSlaveCore<A> + I2cSlaveBuffer<A> + I2cSlaveEventSync<A> | |
| { | |
| } | |
| /// Blanket implementation: any type implementing core + buffer + sync events gets sync slave | |
| impl<T, A: AddressMode> I2cSlaveSync<A> for T where | |
| T: I2cSlaveCore<A> + I2cSlaveBuffer<A> + I2cSlaveEventSync<A> | |
| { | |
| } | |
| /// Combined trait for controllers supporting both master and slave modes | |
| /// | |
| /// This is a convenience trait for hardware that supports both modes. | |
| /// Implementations get this automatically via blanket implementation. | |
| pub trait I2cMasterSlave<A: AddressMode = SevenBitAddress>: | |
| super::I2cMaster<A> + I2cSlaveSync<A> | |
| { | |
| } | |
| /// Blanket implementation: any type implementing both master and sync slave gets this trait | |
| impl<T, A: AddressMode> I2cMasterSlave<A> for T where T: super::I2cMaster<A> + I2cSlaveSync<A> {} | |
| } | |
| /// Re-export slave traits for convenience | |
| pub use slave::{ | |
| I2cMasterSlave, I2cSlaveBasic, I2cSlaveBuffer, I2cSlaveCore, I2cSlaveEventSync, | |
| I2cSlaveInterrupts, I2cSlaveSync, | |
| }; |