diff --git a/CHANGELOG.md b/CHANGELOG.md index 7a019a36d..2616fa700 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ### Changed - 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 modules depending on the execution model: `blocking` and `nb` (non-blocking). +- Re-export `nb::{block!, Error, Result}` to avoid version mismatches. These should be used instead of + importing the `nb` crate directly in dependendent crates. ## [v1.0.0-alpha.4] - 2020-11-11 diff --git a/src/digital.rs b/src/blocking/digital.rs similarity index 95% rename from src/digital.rs rename to src/blocking/digital.rs index d29d87d17..fb3c92752 100644 --- a/src/digital.rs +++ b/src/blocking/digital.rs @@ -7,7 +7,7 @@ use core::{convert::From, ops::Not}; /// Conversion from `bool` and logical negation are also implemented /// for this type. /// ```rust -/// # use embedded_hal::digital::PinState; +/// # use embedded_hal::blocking::digital::PinState; /// let state = PinState::from(false); /// assert_eq!(state, PinState::Low); /// assert_eq!(!state, PinState::High); @@ -100,8 +100,8 @@ pub trait ToggleableOutputPin { /// toggleable by software. /// /// ``` -/// use embedded_hal::digital::{OutputPin, StatefulOutputPin, ToggleableOutputPin}; -/// use embedded_hal::digital::toggleable; +/// use embedded_hal::blocking::digital::{OutputPin, StatefulOutputPin, ToggleableOutputPin}; +/// use embedded_hal::blocking::digital::toggleable; /// use core::convert::Infallible; /// /// /// A virtual output pin that exists purely in software @@ -182,7 +182,7 @@ pub trait InputPin { /// /// ``` /// use core::time::Duration; -/// use embedded_hal::digital::{IoPin, InputPin, OutputPin}; +/// use embedded_hal::blocking::digital::{IoPin, InputPin, OutputPin}; /// /// pub fn ping_and_read( /// mut pin: TOutputPin, delay_fn: &dyn Fn(Duration) -> ()) -> Result diff --git a/src/blocking/mod.rs b/src/blocking/mod.rs index 3a050f6d2..9c98925a2 100644 --- a/src/blocking/mod.rs +++ b/src/blocking/mod.rs @@ -5,7 +5,11 @@ //! Implementing that marker trait will opt in your type into a blanket implementation. pub mod delay; +pub mod digital; pub mod i2c; +pub mod pwm; +pub mod qei; pub mod rng; pub mod serial; pub mod spi; +pub mod watchdog; diff --git a/src/pwm.rs b/src/blocking/pwm.rs similarity index 98% rename from src/pwm.rs rename to src/blocking/pwm.rs index 1a94990f6..ed02a17d7 100644 --- a/src/pwm.rs +++ b/src/blocking/pwm.rs @@ -34,7 +34,7 @@ /// # impl U32Ext for u32 { fn khz(self) -> KiloHertz { KiloHertz(self) } } /// # enum Channel { _1, _2 } /// # struct Pwm1; -/// # impl hal::pwm::Pwm for Pwm1 { +/// # impl hal::blocking::pwm::Pwm for Pwm1 { /// # type Error = Infallible; /// # type Channel = Channel; /// # type Time = KiloHertz; diff --git a/src/qei.rs b/src/blocking/qei.rs similarity index 90% rename from src/qei.rs rename to src/blocking/qei.rs index b8a44dbb6..fc5e732bb 100644 --- a/src/qei.rs +++ b/src/blocking/qei.rs @@ -38,14 +38,14 @@ /// # trait U32Ext { fn s(self) -> Seconds; } /// # impl U32Ext for u32 { fn s(self) -> Seconds { Seconds(self) } } /// # struct Qei1; -/// # impl hal::qei::Qei for Qei1 { +/// # impl hal::blocking::qei::Qei for Qei1 { /// # type Error = Infallible; /// # type Count = u16; /// # fn count(&self) -> Result { Ok(0) } -/// # fn direction(&self) -> Result<::hal::qei::Direction, Self::Error> { unimplemented!() } +/// # fn direction(&self) -> Result<::hal::blocking::qei::Direction, Self::Error> { unimplemented!() } /// # } /// # struct Timer6; -/// # impl hal::timer::CountDown for Timer6 { +/// # impl hal::nb::timer::CountDown for Timer6 { /// # type Error = Infallible; /// # type Time = Seconds; /// # fn start(&mut self, _: T) -> Result<(), Infallible> where T: Into { Ok(()) } diff --git a/src/blocking/serial.rs b/src/blocking/serial.rs index 95e3fec64..5c70fa352 100644 --- a/src/blocking/serial.rs +++ b/src/blocking/serial.rs @@ -23,13 +23,13 @@ pub trait Write { pub mod write { /// Marker trait to opt into default blocking write implementation /// - /// Implementers of [`serial::Write`] can implement this marker trait + /// Implementers of [`nonblocking::serial::Write`] can implement this marker trait /// for their type. Doing so will automatically provide the default /// implementation of [`blocking::serial::Write`] for the type. /// - /// [`serial::Write`]: ../../serial/trait.Write.html + /// [`nonblocking::serial::Write`]: ../../nonblocking/serial/trait.Write.html /// [`blocking::serial::Write`]: ../trait.Write.html - pub trait Default: crate::serial::Write {} + pub trait Default: crate::nb::serial::Write {} impl crate::blocking::serial::Write for S where diff --git a/src/blocking/spi.rs b/src/blocking/spi.rs index 3548dd29f..2e6a8f8ee 100644 --- a/src/blocking/spi.rs +++ b/src/blocking/spi.rs @@ -32,8 +32,8 @@ pub trait WriteIter { /// Blocking transfer pub mod transfer { /// Default implementation of `blocking::spi::Transfer` for implementers of - /// `spi::FullDuplex` - pub trait Default: crate::spi::FullDuplex {} + /// `nonblocking::spi::FullDuplex` + pub trait Default: crate::nb::spi::FullDuplex {} impl crate::blocking::spi::Transfer for S where @@ -55,8 +55,9 @@ pub mod transfer { /// Blocking write pub mod write { - /// Default implementation of `blocking::spi::Write` for implementers of `spi::FullDuplex` - pub trait Default: crate::spi::FullDuplex {} + /// Default implementation of `blocking::spi::Write` for implementers + /// of `nonblocking::spi::FullDuplex` + pub trait Default: crate::nb::spi::FullDuplex {} impl crate::blocking::spi::Write for S where @@ -79,8 +80,8 @@ pub mod write { /// Blocking write (iterator version) pub mod write_iter { /// Default implementation of `blocking::spi::WriteIter` for implementers of - /// `spi::FullDuplex` - pub trait Default: crate::spi::FullDuplex {} + /// `nonblocking::spi::FullDuplex` + pub trait Default: crate::nb::spi::FullDuplex {} impl crate::blocking::spi::WriteIter for S where diff --git a/src/watchdog.rs b/src/blocking/watchdog.rs similarity index 100% rename from src/watchdog.rs rename to src/blocking/watchdog.rs diff --git a/src/fmt.rs b/src/fmt.rs index f63d68861..81e23cef5 100644 --- a/src/fmt.rs +++ b/src/fmt.rs @@ -3,7 +3,7 @@ //! TODO write example of usage use core::fmt::{Result, Write}; -impl Write for dyn crate::serial::Write + '_ +impl Write for dyn crate::nb::serial::Write + '_ where Word: From, { diff --git a/src/lib.rs b/src/lib.rs index cf4b7efe1..8522caaa5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -145,7 +145,7 @@ //! // omitted: other error variants //! } //! -//! impl hal::serial::Read for Serial { +//! impl hal::nb::serial::Read for Serial { //! type Error = Error; //! //! fn read(&mut self) -> nb::Result { @@ -167,7 +167,7 @@ //! } //! } //! -//! impl hal::serial::Write for Serial { +//! impl hal::nb::serial::Write for Serial { //! type Error = Error; //! //! fn write(&mut self, byte: u8) -> nb::Result<(), Error> { @@ -198,7 +198,7 @@ //! //! ``` //! use crate::stm32f1xx_hal::Serial1; -//! use embedded_hal::serial::Write; +//! use embedded_hal::nb::serial::Write; //! use nb::block; //! //! # fn main() { @@ -248,7 +248,7 @@ //! //! fn write_all(serial: &mut S, buffer: &[u8]) -> Result<(), S::Error> //! where -//! S: hal::serial::Write +//! S: hal::nb::serial::Write //! { //! for &byte in buffer { //! block!(serial.write(byte))?; @@ -281,8 +281,8 @@ //! timeout: T::Time, //! ) -> Result> //! where -//! T: hal::timer::CountDown, -//! S: hal::serial::Read, +//! T: hal::nb::timer::CountDown, +//! S: hal::nb::serial::Read, //! { //! timer.start(timeout).map_err(Error::TimedOut)?; //! @@ -325,7 +325,7 @@ //! //! fn flush(serial: &mut S, cb: &mut CircularBuffer) //! where -//! S: hal::serial::Write, +//! S: hal::nb::serial::Write, //! { //! loop { //! if let Some(byte) = cb.peek() { @@ -389,7 +389,7 @@ //! # fn deref_mut(&mut self) -> &mut T { self.0 } //! # } //! # struct Serial1; -//! # impl hal::serial::Write for Serial1 { +//! # impl hal::nb::serial::Write for Serial1 { //! # type Error = Infallible; //! # fn write(&mut self, _: u8) -> nb::Result<(), Infallible> { Err(::nb::Error::WouldBlock) } //! # fn flush(&mut self) -> nb::Result<(), Infallible> { Err(::nb::Error::WouldBlock) } @@ -408,19 +408,10 @@ #![deny(missing_docs)] #![no_std] -pub mod adc; pub mod blocking; -pub mod capture; -pub mod digital; pub mod fmt; +pub mod nb; pub mod prelude; -pub mod pwm; -pub mod qei; -pub mod rng; -pub mod serial; -pub mod spi; -pub mod timer; -pub mod watchdog; mod private { use crate::blocking::i2c::{SevenBitAddress, TenBitAddress}; diff --git a/src/adc.rs b/src/nb/adc.rs similarity index 97% rename from src/adc.rs rename to src/nb/adc.rs index 0a8551e02..17de484dd 100644 --- a/src/adc.rs +++ b/src/nb/adc.rs @@ -8,7 +8,7 @@ /// /// ``` /// # use core::marker::PhantomData; -/// # use embedded_hal::adc::Channel; +/// # use embedded_hal::nb::adc::Channel; /// /// struct Adc1; // Example ADC with single bank of 8 channels /// struct Gpio1Pin1(PhantomData); @@ -55,7 +55,7 @@ pub trait Channel { /// of the request (in contrast to continuous asynchronous sampling). /// /// ``` -/// use embedded_hal::adc::{Channel, OneShot}; +/// use embedded_hal::nb::adc::{Channel, OneShot}; /// /// struct MyAdc; // 10-bit ADC, with 5 channels /// # impl MyAdc { diff --git a/src/capture.rs b/src/nb/capture.rs similarity index 98% rename from src/capture.rs rename to src/nb/capture.rs index bd3ef5df0..6feee5b48 100644 --- a/src/capture.rs +++ b/src/nb/capture.rs @@ -36,7 +36,7 @@ /// # impl U32Ext for u32 { fn ms(self) -> MilliSeconds { MilliSeconds(self) } } /// # struct Capture1; /// # enum Channel { _1 } -/// # impl hal::capture::Capture for Capture1 { +/// # impl hal::nb::capture::Capture for Capture1 { /// # type Error = Infallible; /// # type Capture = u16; /// # type Channel = Channel; diff --git a/src/nb/mod.rs b/src/nb/mod.rs new file mode 100644 index 000000000..ee3df2ae3 --- /dev/null +++ b/src/nb/mod.rs @@ -0,0 +1,23 @@ +//! Non-blocking API +//! +//! These traits make use of the [`nb`] crate +//! (*please go read that crate documentation before continuing*) to abstract over +//! the execution model and to also provide an optional blocking operation mode. +//! +//! The `nb::Result` enum is used to add an [`Error::WouldBlock`] variant to the errors +//! of the traits. Using this it is possible to execute actions in a non-blocking +//! way. +//! +//! `block!`, `Result` and `Error` from the [`nb`] crate are re-exported here to avoid +//! crate version mismatches. These should be used instead of importing the `nb` crate +//! directly again in dependent crates. +//! +//! [`nb`]: https://crates.io/crates/nb + +pub use nb::{block, Error, Result}; +pub mod adc; +pub mod capture; +pub mod rng; +pub mod serial; +pub mod spi; +pub mod timer; diff --git a/src/rng.rs b/src/nb/rng.rs similarity index 97% rename from src/rng.rs rename to src/nb/rng.rs index 9358fbcc2..4e2b82128 100644 --- a/src/rng.rs +++ b/src/nb/rng.rs @@ -1,7 +1,5 @@ //! Random Number Generator Interface -use nb; - /// Nonblocking stream of random bytes. pub trait Read { /// An enumeration of RNG errors. diff --git a/src/serial.rs b/src/nb/serial.rs similarity index 100% rename from src/serial.rs rename to src/nb/serial.rs diff --git a/src/spi.rs b/src/nb/spi.rs similarity index 100% rename from src/spi.rs rename to src/nb/spi.rs diff --git a/src/timer.rs b/src/nb/timer.rs similarity index 98% rename from src/timer.rs rename to src/nb/timer.rs index e2b3b5c39..38246a768 100644 --- a/src/timer.rs +++ b/src/nb/timer.rs @@ -47,7 +47,7 @@ /// # pub fn on(&mut self) {} /// # } /// # struct Timer6; -/// # impl hal::timer::CountDown for Timer6 { +/// # impl hal::nb::timer::CountDown for Timer6 { /// # type Error = Infallible; /// # type Time = Seconds; /// # fn start(&mut self, _: T) -> Result<(), Self::Error> where T: Into { Ok(()) } diff --git a/src/prelude.rs b/src/prelude.rs index 9ec6fb52d..7ea09b34d 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -3,10 +3,12 @@ //! The traits have been renamed to avoid collisions with other items when //! performing a glob import. -pub use crate::adc::Channel as _embedded_hal_adc_Channel; -pub use crate::adc::OneShot as _embedded_hal_adc_OneShot; pub use crate::blocking::delay::DelayMs as _embedded_hal_blocking_delay_DelayMs; pub use crate::blocking::delay::DelayUs as _embedded_hal_blocking_delay_DelayUs; +pub use crate::blocking::digital::InputPin as _embedded_hal_blocking_digital_InputPin; +pub use crate::blocking::digital::OutputPin as _embedded_hal_blocking_digital_OutputPin; +pub use crate::blocking::digital::StatefulOutputPin as _embedded_hal_blocking_digital_StatefulOutputPin; +pub use crate::blocking::digital::ToggleableOutputPin as _embedded_hal_blocking_digital_ToggleableOutputPin; pub use crate::blocking::i2c::{ Read as _embedded_hal_blocking_i2c_Read, Transactional as _embedded_hal_blocking_i2c_Transactional, @@ -14,27 +16,25 @@ pub use crate::blocking::i2c::{ WriteIterRead as _embedded_hal_blocking_i2c_WriteIterRead, WriteRead as _embedded_hal_blocking_i2c_WriteRead, }; +pub use crate::blocking::pwm::Pwm as _embedded_hal_blocking_Pwm; +pub use crate::blocking::pwm::PwmPin as _embedded_hal_blocking_PwmPin; +pub use crate::blocking::qei::Qei as _embedded_hal_blocking_Qei; pub use crate::blocking::rng::Read as _embedded_hal_blocking_rng_Read; pub use crate::blocking::serial::Write as _embedded_hal_blocking_serial_Write; pub use crate::blocking::spi::{ Transfer as _embedded_hal_blocking_spi_Transfer, Write as _embedded_hal_blocking_spi_Write, WriteIter as _embedded_hal_blocking_spi_WriteIter, }; -pub use crate::capture::Capture as _embedded_hal_Capture; -pub use crate::digital::InputPin as _embedded_hal_digital_InputPin; -pub use crate::digital::OutputPin as _embedded_hal_digital_OutputPin; -pub use crate::digital::StatefulOutputPin as _embedded_hal_digital_StatefulOutputPin; -pub use crate::digital::ToggleableOutputPin as _embedded_hal_digital_ToggleableOutputPin; -pub use crate::pwm::Pwm as _embedded_hal_Pwm; -pub use crate::pwm::PwmPin as _embedded_hal_PwmPin; -pub use crate::qei::Qei as _embedded_hal_Qei; -pub use crate::rng::Read as _embedded_hal_rng_Read; -pub use crate::serial::Read as _embedded_hal_serial_Read; -pub use crate::serial::Write as _embedded_hal_serial_Write; -pub use crate::spi::FullDuplex as _embedded_hal_spi_FullDuplex; -pub use crate::timer::Cancel as _embedded_hal_timer_Cancel; -pub use crate::timer::CountDown as _embedded_hal_timer_CountDown; -pub use crate::timer::Periodic as _embedded_hal_timer_Periodic; -pub use crate::watchdog::Disable as _embedded_hal_watchdog_Disable; -pub use crate::watchdog::Enable as _embedded_hal_watchdog_Enable; -pub use crate::watchdog::Watchdog as _embedded_hal_watchdog_Watchdog; +pub use crate::blocking::watchdog::Disable as _embedded_hal_blocking_watchdog_Disable; +pub use crate::blocking::watchdog::Enable as _embedded_hal_blocking_watchdog_Enable; +pub use crate::blocking::watchdog::Watchdog as _embedded_hal_blocking_watchdog_Watchdog; +pub use crate::nb::adc::Channel as _embedded_hal_nb_adc_Channel; +pub use crate::nb::adc::OneShot as _embedded_hal_nb_adc_OneShot; +pub use crate::nb::capture::Capture as _embedded_hal_nb_Capture; +pub use crate::nb::rng::Read as _embedded_hal_nb_rng_Read; +pub use crate::nb::serial::Read as _embedded_hal_nb_serial_Read; +pub use crate::nb::serial::Write as _embedded_hal_nb_serial_Write; +pub use crate::nb::spi::FullDuplex as _embedded_hal_nb_spi_FullDuplex; +pub use crate::nb::timer::Cancel as _embedded_hal_nb_timer_Cancel; +pub use crate::nb::timer::CountDown as _embedded_hal_nb_timer_CountDown; +pub use crate::nb::timer::Periodic as _embedded_hal_nb_timer_Periodic;