From a31192fd27a7a0e24d0fb1b4a4f88001a2992ac1 Mon Sep 17 00:00:00 2001 From: luojia65 Date: Tue, 16 Jun 2020 17:51:13 +0800 Subject: [PATCH 1/2] Another probable watchdog API design (issue #98) --- src/prelude.rs | 4 ++-- src/watchdog.rs | 28 ++++++++++++++++++++-------- 2 files changed, 22 insertions(+), 10 deletions(-) diff --git a/src/prelude.rs b/src/prelude.rs index 223c7222a..8967a4275 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -28,5 +28,5 @@ pub use crate::serial::Write as _embedded_hal_serial_Write; pub use crate::spi::FullDuplex as _embedded_hal_spi_FullDuplex; pub use crate::timer::CountDown as _embedded_hal_timer_CountDown; 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; +pub use crate::watchdog::Disable as _embedded_hal_watchdog_Disable; +pub use crate::watchdog::Enable as _embedded_hal_watchdog_Enable; diff --git a/src/watchdog.rs b/src/watchdog.rs index b0a2efabf..b6a0c4c23 100644 --- a/src/watchdog.rs +++ b/src/watchdog.rs @@ -15,8 +15,8 @@ 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; @@ -24,20 +24,32 @@ pub trait WatchdogEnable { /// Unit of time used by the watchdog type Time; - /// 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(&mut self, period: T) -> Result<(), Self::Error> + /// 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. + /// + /// This consumes the value and returns the `Watchdog` trait that you must + /// `feed()`. + fn try_start(&mut self, period: T) -> Result where T: Into; } /// Disables a running watchdog timer so the processor won't be reset. -pub trait WatchdogDisable { - /// An enumeration of `WatchdogDisable` errors. +pub trait Disable { + /// An enumeration of `Disable` errors. /// /// For infallible implementations, will be `Infallible` type Error; + /// Disabled watchdog instance that can be enabled. + type Target: Enable; + /// Disables the watchdog - fn try_disable(&mut self) -> Result<(), Self::Error>; + /// + /// This stops the watchdog and returns the `Enable` trait so that + /// it can be started again. + fn try_disable(&mut self) -> Result; } From 8a7500b26283774598c864fa93120d5f56df2579 Mon Sep 17 00:00:00 2001 From: luojia65 Date: Tue, 16 Jun 2020 17:53:38 +0800 Subject: [PATCH 2/2] Improve watchdog API design using move semantics Co-authored-by: Diego Barrios Romero Co-authored-by: Daniel Egger <@therealprof:matrix.org> --- CHANGELOG.md | 4 ++++ src/prelude.rs | 2 +- src/watchdog.rs | 25 +++++++++++++++---------- 3 files changed, 20 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d5b14d86b..b50a54a9a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ## [Unreleased] +### Changed + +- 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 *** This is an alpha release with breaking changes (sorry) *** diff --git a/src/prelude.rs b/src/prelude.rs index 8967a4275..37d233bfa 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -27,6 +27,6 @@ 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::CountDown as _embedded_hal_timer_CountDown; -pub use crate::watchdog::Watchdog as _embedded_hal_watchdog_Watchdog; 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; diff --git a/src/watchdog.rs b/src/watchdog.rs index b6a0c4c23..053fbf47e 100644 --- a/src/watchdog.rs +++ b/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. /// @@ -21,23 +21,28 @@ pub trait Enable { /// 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()` + /// 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. + /// Starts the watchdog with a given period, typically once this is done + /// 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(&mut self, period: T) -> Result + fn try_start(self, period: T) -> Result where T: Into; } /// Disables a running watchdog timer so the processor won't be reset. +/// +/// 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. /// @@ -47,9 +52,9 @@ pub trait Disable { /// Disabled watchdog instance that can be enabled. type Target: Enable; - /// Disables the watchdog + /// Disables the watchdog. /// - /// This stops the watchdog and returns the `Enable` trait so that - /// it can be started again. - fn try_disable(&mut self) -> Result; + /// This stops the watchdog and returns an instance implementing the + /// `Enable` trait so that it can be started again. + fn try_disable(self) -> Result; }