Move execution-model-independent definitions up

Author: eldruin

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Swap PWM channel arguments to references
 - All trait methods have been renamed to remove the `try_` prefix (i.e. `try_send` -> `send`) for consistency.
 - Moved all traits into two sub modules for each feature depending on the execution model: `blocking` and `nb` (non-blocking). For example, the spi traits can now be found under `embedded_hal::spi::blocking` or `embedded_hal::spi::nb`.
+- Execution-model-independent definitions have been moved into the feature module. For example, SPI `Phase` is now defined in `embedded_hal::spi::Phase`. For convenience, these definitions are reexported in both of its blocking and non-blocking submodules.
 - Re-export `nb::{block!, Error, Result}` to avoid version mismatches. These should be used instead of
   importing the `nb` crate directly in dependent crates.
 - `blocking::Serial`: renamed `bwrite_all` to `write`, `bflush` to `flush.

src/adc/mod.rs

@@ -1,3 +1,52 @@
 //! Analog-digital conversion traits
 
 pub mod nb;
+
+/// A marker trait to identify MCU pins that can be used as inputs to an ADC channel.
+///
+/// This marker trait denotes an object, i.e. a GPIO pin, that is ready for use as an input to the
+/// ADC. As ADCs channels can be supplied by multiple pins, this trait defines the relationship
+/// between the physical interface and the ADC sampling buffer.
+///
+/// ```
+/// # use core::marker::PhantomData;
+/// # use embedded_hal::adc::nb::Channel;
+///
+/// struct Adc1; // Example ADC with single bank of 8 channels
+/// struct Gpio1Pin1<MODE>(PhantomData<MODE>);
+/// struct Analog(()); // marker type to denote a pin in "analog" mode
+///
+/// // GPIO 1 pin 1 can supply an ADC channel when it is configured in Analog mode
+/// impl Channel<Adc1> for Gpio1Pin1<Analog> {
+///     type ID = u8; // ADC channels are identified numerically
+///
+///     fn channel(&self) -> Self::ID {
+///         7_u8 // GPIO pin 1 is connected to ADC channel 7
+///     }
+/// }
+///
+/// struct Adc2; // ADC with two banks of 16 channels
+/// struct Gpio2PinA<MODE>(PhantomData<MODE>);
+/// struct AltFun(()); // marker type to denote some alternate function mode for the pin
+///
+/// // GPIO 2 pin A can supply an ADC channel when it's configured in some alternate function mode
+/// impl Channel<Adc2> for Gpio2PinA<AltFun> {
+///     type ID = (u8, u8); // ADC channels are identified by bank number and channel number
+///
+///     fn channel(&self) -> Self::ID {
+///         (0, 3) // bank 0 channel 3
+///     }
+/// }
+/// ```
+pub trait Channel<ADC> {
+    /// Channel ID type
+    ///
+    /// A type used to identify this ADC channel. For example, if the ADC has eight channels, this
+    /// might be a `u8`. If the ADC has multiple banks of channels, it could be a tuple, like
+    /// `(u8: bank_id, u8: channel_id)`.
+    type ID: Copy;
+
+    /// Get the specific ID that identifies this channel, for example `0_u8` for the first ADC
+    /// channel, if Self::ID is u8.
+    fn channel(&self) -> Self::ID;
+}

src/adc/nb.rs

@@ -1,53 +1,6 @@
 //! Analog-digital conversion traits
 
-/// A marker trait to identify MCU pins that can be used as inputs to an ADC channel.
-///
-/// This marker trait denotes an object, i.e. a GPIO pin, that is ready for use as an input to the
-/// ADC. As ADCs channels can be supplied by multiple pins, this trait defines the relationship
-/// between the physical interface and the ADC sampling buffer.
-///
-/// ```
-/// # use core::marker::PhantomData;
-/// # use embedded_hal::adc::nb::Channel;
-///
-/// struct Adc1; // Example ADC with single bank of 8 channels
-/// struct Gpio1Pin1<MODE>(PhantomData<MODE>);
-/// struct Analog(()); // marker type to denote a pin in "analog" mode
-///
-/// // GPIO 1 pin 1 can supply an ADC channel when it is configured in Analog mode
-/// impl Channel<Adc1> for Gpio1Pin1<Analog> {
-///     type ID = u8; // ADC channels are identified numerically
-///
-///     fn channel(&self) -> Self::ID {
-///         7_u8 // GPIO pin 1 is connected to ADC channel 7
-///     }
-/// }
-///
-/// struct Adc2; // ADC with two banks of 16 channels
-/// struct Gpio2PinA<MODE>(PhantomData<MODE>);
-/// struct AltFun(()); // marker type to denote some alternate function mode for the pin
-///
-/// // GPIO 2 pin A can supply an ADC channel when it's configured in some alternate function mode
-/// impl Channel<Adc2> for Gpio2PinA<AltFun> {
-///     type ID = (u8, u8); // ADC channels are identified by bank number and channel number
-///
-///     fn channel(&self) -> Self::ID {
-///         (0, 3) // bank 0 channel 3
-///     }
-/// }
-/// ```
-pub trait Channel<ADC> {
-    /// Channel ID type
-    ///
-    /// A type used to identify this ADC channel. For example, if the ADC has eight channels, this
-    /// might be a `u8`. If the ADC has multiple banks of channels, it could be a tuple, like
-    /// `(u8: bank_id, u8: channel_id)`.
-    type ID: Copy;
-
-    /// Get the specific ID that identifies this channel, for example `0_u8` for the first ADC
-    /// channel, if Self::ID is u8.
-    fn channel(&self) -> Self::ID;
-}
+pub use super::Channel;
 
 /// ADCs that sample on single channels per request, and do so at the time of the request.
 ///

src/digital/blocking.rs

@@ -4,45 +4,7 @@
 //! traits. To save boilerplate when that's the case a `Default` marker trait may be provided.
 //! Implementing that marker trait will opt in your type into a blanket implementation.
 
-use core::{convert::From, ops::Not};
-
-/// Digital output pin state
-///
-/// Conversion from `bool` and logical negation are also implemented
-/// for this type.
-/// ```rust
-/// # use embedded_hal::digital::blocking::PinState;
-/// let state = PinState::from(false);
-/// assert_eq!(state, PinState::Low);
-/// assert_eq!(!state, PinState::High);
-/// ```
-#[derive(Debug, PartialEq, Eq, Clone, Copy)]
-pub enum PinState {
-    /// Low pin state
-    Low,
-    /// High pin state
-    High,
-}
-
-impl From<bool> for PinState {
-    fn from(value: bool) -> Self {
-        match value {
-            false => PinState::Low,
-            true => PinState::High,
-        }
-    }
-}
-
-impl Not for PinState {
-    type Output = PinState;
-
-    fn not(self) -> Self::Output {
-        match self {
-            PinState::High => PinState::Low,
-            PinState::Low => PinState::High,
-        }
-    }
-}
+pub use super::PinState;
 
 /// Single digital push-pull output pin
 pub trait OutputPin {

src/digital/mod.rs

@@ -1,3 +1,43 @@
 //! Digital I/O traits
 
 pub mod blocking;
+
+use core::{convert::From, ops::Not};
+
+/// Digital output pin state
+///
+/// Conversion from `bool` and logical negation are also implemented
+/// for this type.
+/// ```rust
+/// # use embedded_hal::digital::blocking::PinState;
+/// let state = PinState::from(false);
+/// assert_eq!(state, PinState::Low);
+/// assert_eq!(!state, PinState::High);
+/// ```
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum PinState {
+    /// Low pin state
+    Low,
+    /// High pin state
+    High,
+}
+
+impl From<bool> for PinState {
+    fn from(value: bool) -> Self {
+        match value {
+            false => PinState::Low,
+            true => PinState::High,
+        }
+    }
+}
+
+impl Not for PinState {
+    type Output = PinState;
+
+    fn not(self) -> Self::Output {
+        match self {
+            PinState::High => PinState::Low,
+            PinState::Low => PinState::High,
+        }
+    }
+}

src/i2c/blocking.rs

@@ -99,22 +99,7 @@
 //! }
 //! ```
 
-use crate::private;
-
-/// Address mode (7-bit / 10-bit)
-///
-/// Note: This trait is sealed and should not be implemented outside of this crate.
-pub trait AddressMode: private::Sealed {}
-
-/// 7-bit address mode type
-pub type SevenBitAddress = u8;
-
-/// 10-bit address mode type
-pub type TenBitAddress = u16;
-
-impl AddressMode for SevenBitAddress {}
-
-impl AddressMode for TenBitAddress {}
+pub use super::{AddressMode, SevenBitAddress, TenBitAddress};
 
 /// Blocking read
 pub trait Read<A: AddressMode = SevenBitAddress> {

src/i2c/mod.rs

@@ -1,3 +1,20 @@
 //! I2C traits
 
 pub mod blocking;
+
+use crate::private;
+
+/// Address mode (7-bit / 10-bit)
+///
+/// Note: This trait is sealed and should not be implemented outside of this crate.
+pub trait AddressMode: private::Sealed {}
+
+/// 7-bit address mode type
+pub type SevenBitAddress = u8;
+
+/// 10-bit address mode type
+pub type TenBitAddress = u16;
+
+impl AddressMode for SevenBitAddress {}
+
+impl AddressMode for TenBitAddress {}

src/lib.rs

@@ -428,7 +428,7 @@ pub mod timer;
 pub mod watchdog;
 
 mod private {
-    use crate::i2c::blocking::{SevenBitAddress, TenBitAddress};
+    use crate::i2c::{SevenBitAddress, TenBitAddress};
     pub trait Sealed {}
 
     impl Sealed for SevenBitAddress {}

src/qei/blocking.rs

@@ -1,5 +1,7 @@
 //! Quadrature encoder interface
 
+pub use super::Direction;
+
 /// Quadrature encoder interface
 ///
 /// # Examples
@@ -68,12 +70,3 @@ pub trait Qei {
     /// Returns the count direction
     fn direction(&self) -> Result<Direction, Self::Error>;
 }
-
-/// Count direction
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
-pub enum Direction {
-    /// 3, 2, 1
-    Downcounting,
-    /// 1, 2, 3
-    Upcounting,
-}

src/qei/mod.rs

@@ -1,3 +1,12 @@
 //! Quadrature encoder interface traits
 
 pub mod blocking;
+
+/// Count direction
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum Direction {
+    /// 3, 2, 1
+    Downcounting,
+    /// 1, 2, 3
+    Upcounting,
+}

src/spi/blocking.rs

@@ -4,6 +4,7 @@
 //! traits. To save boilerplate when that's the case a `Default` marker trait may be provided.
 //! Implementing that marker trait will opt in your type into a blanket implementation.
 
+pub use super::{Mode, Phase, Polarity, MODE_0, MODE_1, MODE_2, MODE_3};
 /// Blocking transfer
 pub trait Transfer<W> {
     /// Error type

src/spi/mod.rs

@@ -2,3 +2,54 @@
 
 pub mod blocking;
 pub mod nb;
+
+/// Clock polarity
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub enum Polarity {
+    /// Clock signal low when idle
+    IdleLow,
+    /// Clock signal high when idle
+    IdleHigh,
+}
+
+/// Clock phase
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub enum Phase {
+    /// Data in "captured" on the first clock transition
+    CaptureOnFirstTransition,
+    /// Data in "captured" on the second clock transition
+    CaptureOnSecondTransition,
+}
+
+/// SPI mode
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub struct Mode {
+    /// Clock polarity
+    pub polarity: Polarity,
+    /// Clock phase
+    pub phase: Phase,
+}
+
+/// Helper for CPOL = 0, CPHA = 0
+pub const MODE_0: Mode = Mode {
+    polarity: Polarity::IdleLow,
+    phase: Phase::CaptureOnFirstTransition,
+};
+
+/// Helper for CPOL = 0, CPHA = 1
+pub const MODE_1: Mode = Mode {
+    polarity: Polarity::IdleLow,
+    phase: Phase::CaptureOnSecondTransition,
+};
+
+/// Helper for CPOL = 1, CPHA = 0
+pub const MODE_2: Mode = Mode {
+    polarity: Polarity::IdleHigh,
+    phase: Phase::CaptureOnFirstTransition,
+};
+
+/// Helper for CPOL = 1, CPHA = 1
+pub const MODE_3: Mode = Mode {
+    polarity: Polarity::IdleHigh,
+    phase: Phase::CaptureOnSecondTransition,
+};