embedded_hal_bus/spi/
atomic.rs

Help
1use embedded_hal::delay::DelayNs;
2use embedded_hal::digital::OutputPin;
3use embedded_hal::spi::{Error, ErrorKind, ErrorType, Operation, SpiBus, SpiDevice};
4
5use super::DeviceError;
6use crate::spi::shared::transaction;
7use crate::util::AtomicCell;
8
9/// Atomics-based shared bus [`SpiDevice`] implementation.
10///
11/// This allows for sharing an [`SpiBus`], obtaining multiple [`SpiDevice`] instances,
12/// each with its own `CS` pin.
13///
14/// Sharing is implemented with a [`AtomicDevice`], which consists of an `UnsafeCell` and an `AtomicBool` "locked" flag.
15/// This means it has low overhead, like [`RefCellDevice`](crate::spi::RefCellDevice). Aditionally, it is `Send`,
16/// which allows sharing a single bus across multiple threads (interrupt priority level), like [`CriticalSectionDevice`](crate::spi::CriticalSectionDevice),
17/// while not using critical sections and therefore impacting real-time performance less.
18///
19/// The downside is using a simple `AtomicBool` for locking doesn't prevent two threads from trying to lock it at once.
20/// For example, the main thread can be doing a SPI transaction, and an interrupt fires and tries to do another. In this
21/// case, a `Busy` error is returned that must be handled somehow, usually dropping the data or trying again later.
22///
23/// Note that retrying in a loop on `Busy` errors usually leads to deadlocks. In the above example, it'll prevent the
24/// interrupt handler from returning, which will starve the main thread and prevent it from releasing the lock. If
25/// this is an issue for your use case, you most likely should use [`CriticalSectionDevice`](crate::spi::CriticalSectionDevice) instead.
26///
27/// This primitive is particularly well-suited for applications that have external arbitration
28/// rules that prevent `Busy` errors in the first place, such as the RTIC framework.
29pub struct AtomicDevice<'a, BUS, CS, D> {
30    bus: &'a AtomicCell<BUS>,
31    cs: CS,
32    delay: D,
33}
34
35#[derive(Debug, Copy, Clone)]
36/// Wrapper type for errors returned by [`AtomicDevice`].
37pub enum AtomicError<T: Error> {
38    /// This error is returned if the SPI bus was already in use when an operation was attempted,
39    /// which indicates that the driver requirements are not being met with regard to
40    /// synchronization.
41    Busy,
42
43    /// An SPI-related error occurred, and the internal error should be inspected.
44    Other(T),
45}
46
47impl<'a, BUS, CS, D> AtomicDevice<'a, BUS, CS, D> {
48    /// Create a new [`AtomicDevice`].
49    ///
50    /// This sets the `cs` pin high, and returns an error if that fails. It is recommended
51    /// to set the pin high the moment it's configured as an output, to avoid glitches.
52    #[inline]
53    pub fn new(bus: &'a AtomicCell<BUS>, mut cs: CS, delay: D) -> Result<Self, CS::Error>
54    where
55        CS: OutputPin,
56    {
57        cs.set_high()?;
58        Ok(Self { bus, cs, delay })
59    }
60}
61
62impl<'a, BUS, CS> AtomicDevice<'a, BUS, CS, super::NoDelay>
63where
64    BUS: ErrorType,
65    CS: OutputPin,
66{
67    /// Create a new [`AtomicDevice`] without support for in-transaction delays.
68    ///
69    /// This sets the `cs` pin high, and returns an error if that fails. It is recommended
70    /// to set the pin high the moment it's configured as an output, to avoid glitches.
71    ///
72    /// **Warning**: The returned instance *technically* doesn't comply with the `SpiDevice`
73    /// contract, which mandates delay support. It is relatively rare for drivers to use
74    /// in-transaction delays, so you might still want to use this method because it's more practical.
75    ///
76    /// Note that a future version of the driver might start using delays, causing your
77    /// code to panic. This wouldn't be considered a breaking change from the driver side, because
78    /// drivers are allowed to assume `SpiDevice` implementations comply with the contract.
79    /// If you feel this risk outweighs the convenience of having `cargo` automatically upgrade
80    /// the driver crate, you might want to pin the driver's version.
81    ///
82    /// # Panics
83    ///
84    /// The returned device will panic if you try to execute a transaction
85    /// that contains any operations of type [`Operation::DelayNs`].
86    #[inline]
87    pub fn new_no_delay(bus: &'a AtomicCell<BUS>, mut cs: CS) -> Result<Self, CS::Error>
88    where
89        CS: OutputPin,
90    {
91        cs.set_high()?;
92        Ok(Self {
93            bus,
94            cs,
95            delay: super::NoDelay,
96        })
97    }
98}
99
100impl<T: Error> Error for AtomicError<T> {
101    fn kind(&self) -> ErrorKind {
102        match self {
103            AtomicError::Other(e) => e.kind(),
104            _ => ErrorKind::Other,
105        }
106    }
107}
108
109impl<'a, BUS, CS, D> ErrorType for AtomicDevice<'a, BUS, CS, D>
110where
111    BUS: ErrorType,
112    CS: OutputPin,
113{
114    type Error = AtomicError<DeviceError<BUS::Error, CS::Error>>;
115}
116
117impl<'a, Word: Copy + 'static, BUS, CS, D> SpiDevice<Word> for AtomicDevice<'a, BUS, CS, D>
118where
119    BUS: SpiBus<Word>,
120    CS: OutputPin,
121    D: DelayNs,
122{
123    #[inline]
124    fn transaction(&mut self, operations: &mut [Operation<'_, Word>]) -> Result<(), Self::Error> {
125        self.bus
126            .busy
127            .compare_exchange(
128                false,
129                true,
130                core::sync::atomic::Ordering::SeqCst,
131                core::sync::atomic::Ordering::SeqCst,
132            )
133            .map_err(|_| AtomicError::Busy)?;
134
135        let bus = unsafe { &mut *self.bus.bus.get() };
136
137        let result = transaction(operations, bus, &mut self.delay, &mut self.cs);
138
139        self.bus
140            .busy
141            .store(false, core::sync::atomic::Ordering::SeqCst);
142
143        result.map_err(AtomicError::Other)
144    }
145}
embedded_hal_bus/spi/atomic.rs

embedded_hal_bus/spi/
atomic.rs
