Merge #222

222: Improve watchdog API design using move semantics r=therealprof a=luojia65

This pull request improved watchdog API design. When starting watchdog, we may convert it into another type. We may implement different functions for this type. Or downstream developers can implement `Watchdog` for only an enabled type, to prevent feed to disabled watchdogs or forget to enable before feeding. If we are able to stop this watchdog, it can be converted into the former type.

If current design still need a same type after the watchdog is enabled, they may use `Target = Self`. In this way we create a fallback for earlier designs. 

A simple proof of concept: [here](https://github.com/gd32v-rust/gd32vf103-hal/blob/new-watchdog-design/src/wdog.rs#L155-L169) (L120-L153 for its `Enable` implementation, and there is `Disable` implementation)

Related issue: #98
Earlier discussion: #76 (comment)

Co-authored-by: luojia65 <[email protected]>
Co-authored-by: Luo Jia <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -9,9 +9,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 
 ### Changed
+
 - The method `try_write` from the trait `blocking::i2c::WriteIter` trait
   has been renamed `try_write_iter` for consistency.
 - Updated `nb` dependency to version `1`.
+- The watchdog API now uses move semantics. See [PR](https://github.com/rust-embedded/embedded-hal/pull/222).
 
 ## [v1.0.0-alpha.1] - 2020-06-16
 

src/prelude.rs

@@ -34,6 +34,6 @@ 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::watchdog::WatchdogDisable as _embedded_hal_watchdog_WatchdogDisable;
-pub use crate::watchdog::WatchdogEnable as _embedded_hal_watchdog_WatchdogEnable;

src/watchdog.rs

@@ -1,7 +1,7 @@
 //! Traits for interactions with a processors watchdog timer.
 
 /// Feeds an existing watchdog to ensure the processor isn't reset. Sometimes
-/// commonly referred to as "kicking" or "refreshing".
+/// the "feeding" operation is also referred to as "refreshing".
 pub trait Watchdog {
     /// An enumeration of `Watchdog` errors.
     ///
@@ -15,29 +15,46 @@ pub trait Watchdog {
 
 /// Enables A watchdog timer to reset the processor if software is frozen or
 /// stalled.
-pub trait WatchdogEnable {
-    /// An enumeration of `WatchdogEnable` errors.
+pub trait Enable {
+    /// An enumeration of `Enable` errors.
     ///
     /// For infallible implementations, will be `Infallible`
     type Error;
 
-    /// Unit of time used by the watchdog
+    /// Unit of time used by the watchdog.
     type Time;
 
+    /// The started watchdog that should be `feed()`.
+    type Target: Watchdog;
+
     /// Starts the watchdog with a given period, typically once this is done
-    /// the watchdog needs to be kicked periodically or the processor is reset.
-    fn try_start<T>(&mut self, period: T) -> Result<(), Self::Error>
+    /// the watchdog needs to be `feed()` periodically, or the processor would be
+    /// reset.
+    ///
+    /// This consumes the value and returns the `Watchdog` trait that you must
+    /// `feed()`.
+    fn try_start<T>(self, period: T) -> Result<Self::Target, Self::Error>
     where
         T: Into<Self::Time>;
 }
 
 /// Disables a running watchdog timer so the processor won't be reset.
-pub trait WatchdogDisable {
-    /// An enumeration of `WatchdogDisable` errors.
+///
+/// Not all watchdog timers support disable operation after they've been enabled.
+/// In this case, hardware support libraries would not implement this trait
+/// and hardware-agnostic libraries should consider not requiring it.
+pub trait Disable {
+    /// An enumeration of `Disable` errors.
     ///
     /// For infallible implementations, will be `Infallible`
     type Error;
 
-    /// Disables the watchdog
-    fn try_disable(&mut self) -> Result<(), Self::Error>;
+    /// Disabled watchdog instance that can be enabled.
+    type Target: Enable;
+
+    /// Disables the watchdog.
+    ///
+    /// This stops the watchdog and returns an instance implementing the
+    /// `Enable` trait so that it can be started again.
+    fn try_disable(self) -> Result<Self::Target, Self::Error>;
 }