From cf1323fb67b2841a99bb497d7947ffa772ff354d Mon Sep 17 00:00:00 2001 From: Joshua Salzedo <joshuasalzedo@gmail.com> Date: Sun, 21 Mar 2021 16:45:24 -0700 Subject: [PATCH 1/8] Add module-level documentation for embassy::time --- embassy/src/time/mod.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/embassy/src/time/mod.rs b/embassy/src/time/mod.rs index b45a608dd..b19ab6dbb 100644 --- a/embassy/src/time/mod.rs +++ b/embassy/src/time/mod.rs @@ -1,3 +1,6 @@ +/// Time abstractions +/// To use these abstractions, first call `set_clock` with an instance of an monotonic `Clock`. +/// mod duration; mod instant; mod traits; @@ -14,10 +17,16 @@ pub const TICKS_PER_SECOND: u64 = 32768; static mut CLOCK: Option<&'static dyn Clock> = None; +/// Sets the clock used for the timing abstractions +/// +/// Safety: Sets a mutable global. pub unsafe fn set_clock(clock: &'static dyn Clock) { CLOCK = Some(clock); } +/// Return the current timestamp in ticks. +/// This is guaranteed to be monotonic, i.e. a call to now() will always return +/// a greater or equal value than earler calls. pub(crate) fn now() -> u64 { unsafe { unwrap!(CLOCK, "No clock set").now() } } From d453b9dd95589d95239ea3f86f15da647d253aef Mon Sep 17 00:00:00 2001 From: Joshua Salzedo <joshuasalzedo@gmail.com> Date: Sun, 21 Mar 2021 16:45:48 -0700 Subject: [PATCH 2/8] Add Struct/impl documentation for embassy::time::Duration --- embassy/src/time/duration.rs | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/embassy/src/time/duration.rs b/embassy/src/time/duration.rs index e04afa184..c96007747 100644 --- a/embassy/src/time/duration.rs +++ b/embassy/src/time/duration.rs @@ -26,16 +26,18 @@ impl Duration { self.ticks * 1_000_000 / TICKS_PER_SECOND } + /// Creates a duration from the specified number of clock ticks pub const fn from_ticks(ticks: u64) -> Duration { Duration { ticks } } + /// Creates a duration from the specified number of seconds pub const fn from_secs(secs: u64) -> Duration { Duration { ticks: secs * TICKS_PER_SECOND, } } - + /// Creates a duration from the specified number of milliseconds pub const fn from_millis(millis: u64) -> Duration { Duration { ticks: millis * TICKS_PER_SECOND / 1000, @@ -45,30 +47,34 @@ impl Duration { /* NOTE: us delays may not be as accurate */ + /// Creates a duration from the specified number of microseconds + /// NOTE: Delays this small may be inaccurate. pub const fn from_micros(micros: u64) -> Duration { Duration { ticks: micros * TICKS_PER_SECOND / 1_000_000, } } + /// Adds one Duration to another, returning a new Duration or None in the event of an overflow. pub fn checked_add(self, rhs: Duration) -> Option<Duration> { self.ticks .checked_add(rhs.ticks) .map(|ticks| Duration { ticks }) } - + /// Subtracts one Duration to another, returning a new Duration or None in the event of an overflow. pub fn checked_sub(self, rhs: Duration) -> Option<Duration> { self.ticks .checked_sub(rhs.ticks) .map(|ticks| Duration { ticks }) } + /// Multiplies one Duration to another, returning a new Duration or None in the event of an overflow. pub fn checked_mul(self, rhs: u32) -> Option<Duration> { self.ticks .checked_mul(rhs as _) .map(|ticks| Duration { ticks }) } - + /// Divides one Duration against another, returning a new Duration or None in the event of an overflow. pub fn checked_div(self, rhs: u32) -> Option<Duration> { self.ticks .checked_div(rhs as _) From dcdd768e0360683db747906e4780e5470d1961a1 Mon Sep 17 00:00:00 2001 From: Joshua Salzedo <joshuasalzedo@gmail.com> Date: Sun, 21 Mar 2021 16:45:53 -0700 Subject: [PATCH 3/8] Add Struct/impl documentation for embassy::time::Instant --- embassy/src/time/instant.rs | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/embassy/src/time/instant.rs b/embassy/src/time/instant.rs index 06ab84c75..9a544fc46 100644 --- a/embassy/src/time/instant.rs +++ b/embassy/src/time/instant.rs @@ -6,6 +6,7 @@ use super::{now, Duration}; #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] +/// An Instant in time, based on the MCU's clock ticks since startup. pub struct Instant { ticks: u64, } @@ -14,44 +15,54 @@ impl Instant { pub const MIN: Instant = Instant { ticks: u64::MIN }; pub const MAX: Instant = Instant { ticks: u64::MAX }; + /// Returns an Instant representing the current time. pub fn now() -> Instant { Instant { ticks: now() } } + /// Instant as clock ticks since MCU start. pub const fn from_ticks(ticks: u64) -> Self { Self { ticks } } + /// Instant as milliseconds since MCU start. pub const fn from_millis(millis: u64) -> Self { Self { ticks: millis * TICKS_PER_SECOND as u64 / 1000, } } - + /// Instant representing seconds since MCU start. pub const fn from_secs(seconds: u64) -> Self { Self { ticks: seconds * TICKS_PER_SECOND as u64, } } + /// Instant as ticks since MCU start. + pub const fn as_ticks(&self) -> u64 { self.ticks } + /// Instant as seconds since MCU start. pub const fn as_secs(&self) -> u64 { self.ticks / TICKS_PER_SECOND as u64 } + /// Instant as miliseconds since MCU start. pub const fn as_millis(&self) -> u64 { self.ticks * 1000 / TICKS_PER_SECOND as u64 } + /// Duration between this Instant and another Instant + /// Panics on over/underflow. pub fn duration_since(&self, earlier: Instant) -> Duration { Duration { ticks: self.ticks.checked_sub(earlier.ticks).unwrap(), } } + /// Duration between this Instant and another Instant pub fn checked_duration_since(&self, earlier: Instant) -> Option<Duration> { if self.ticks < earlier.ticks { None @@ -62,6 +73,8 @@ impl Instant { } } + /// Returns the duration since the "earlier" Instant. + /// If the "earlier" instant is in the future, the duration is set to zero. pub fn saturating_duration_since(&self, earlier: Instant) -> Duration { Duration { ticks: if self.ticks < earlier.ticks { @@ -72,6 +85,7 @@ impl Instant { } } + /// Duration elapsed since this Instant. pub fn elapsed(&self) -> Duration { Instant::now() - *self } From f8d63279efed5dfd649118ac89903a8bcb01a09d Mon Sep 17 00:00:00 2001 From: Joshua Salzedo <joshuasalzedo@gmail.com> Date: Sun, 21 Mar 2021 17:01:13 -0700 Subject: [PATCH 4/8] Re-add erroneously removed newlines --- embassy/src/time/duration.rs | 5 ++++- embassy/src/time/instant.rs | 1 + 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/embassy/src/time/duration.rs b/embassy/src/time/duration.rs index c96007747..474d0621b 100644 --- a/embassy/src/time/duration.rs +++ b/embassy/src/time/duration.rs @@ -37,6 +37,7 @@ impl Duration { ticks: secs * TICKS_PER_SECOND, } } + /// Creates a duration from the specified number of milliseconds pub const fn from_millis(millis: u64) -> Duration { Duration { @@ -61,19 +62,21 @@ impl Duration { .checked_add(rhs.ticks) .map(|ticks| Duration { ticks }) } + /// Subtracts one Duration to another, returning a new Duration or None in the event of an overflow. pub fn checked_sub(self, rhs: Duration) -> Option<Duration> { self.ticks .checked_sub(rhs.ticks) .map(|ticks| Duration { ticks }) } - /// Multiplies one Duration to another, returning a new Duration or None in the event of an overflow. + /// Multiplies one Duration to another, returning a new Duration or None in the event of an overflow. pub fn checked_mul(self, rhs: u32) -> Option<Duration> { self.ticks .checked_mul(rhs as _) .map(|ticks| Duration { ticks }) } + /// Divides one Duration against another, returning a new Duration or None in the event of an overflow. pub fn checked_div(self, rhs: u32) -> Option<Duration> { self.ticks diff --git a/embassy/src/time/instant.rs b/embassy/src/time/instant.rs index 9a544fc46..61a61defe 100644 --- a/embassy/src/time/instant.rs +++ b/embassy/src/time/instant.rs @@ -31,6 +31,7 @@ impl Instant { ticks: millis * TICKS_PER_SECOND as u64 / 1000, } } + /// Instant representing seconds since MCU start. pub const fn from_secs(seconds: u64) -> Self { Self { From e363607d70ee088d2da43ec27d4a6257069a6b06 Mon Sep 17 00:00:00 2001 From: Joshua Salzedo <joshuasalzedo@gmail.com> Date: Sun, 21 Mar 2021 17:01:52 -0700 Subject: [PATCH 5/8] Added doc to the embassy::time::Duration struct --- embassy/src/time/duration.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/embassy/src/time/duration.rs b/embassy/src/time/duration.rs index 474d0621b..db0e2cf2d 100644 --- a/embassy/src/time/duration.rs +++ b/embassy/src/time/duration.rs @@ -5,6 +5,7 @@ use super::TICKS_PER_SECOND; #[derive(Debug, Default, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] +/// Represents the difference between [Instant::now()](struct.Instant.html#method.now) and some other Instant pub struct Duration { pub(crate) ticks: u64, } From 10f14747c35f5deab8240c4d792439d72f807bf9 Mon Sep 17 00:00:00 2001 From: Joshua Salzedo <joshuasalzedo@gmail.com> Date: Sun, 21 Mar 2021 17:05:22 -0700 Subject: [PATCH 6/8] Fix module-level docstring --- embassy/src/time/mod.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/embassy/src/time/mod.rs b/embassy/src/time/mod.rs index b19ab6dbb..4e9b5f592 100644 --- a/embassy/src/time/mod.rs +++ b/embassy/src/time/mod.rs @@ -1,6 +1,6 @@ -/// Time abstractions -/// To use these abstractions, first call `set_clock` with an instance of an monotonic `Clock`. -/// +//! Time abstractions +//! To use these abstractions, first call `set_clock` with an instance of an [Clock](trait.Clock.html). +//! mod duration; mod instant; mod traits; From 7988b78107245b33fb8241d0eb04c7110e03f213 Mon Sep 17 00:00:00 2001 From: Joshua Salzedo <joshuasalzedo@gmail.com> Date: Sun, 21 Mar 2021 17:05:36 -0700 Subject: [PATCH 7/8] remove now redundant non-doc comment --- embassy/src/time/duration.rs | 3 --- 1 file changed, 3 deletions(-) diff --git a/embassy/src/time/duration.rs b/embassy/src/time/duration.rs index db0e2cf2d..38b0c0832 100644 --- a/embassy/src/time/duration.rs +++ b/embassy/src/time/duration.rs @@ -46,9 +46,6 @@ impl Duration { } } - /* - NOTE: us delays may not be as accurate - */ /// Creates a duration from the specified number of microseconds /// NOTE: Delays this small may be inaccurate. pub const fn from_micros(micros: u64) -> Duration { From 42be860446856937048efa05538e43408677186e Mon Sep 17 00:00:00 2001 From: Joshua Salzedo <joshuasalzedo@gmail.com> Date: Sun, 21 Mar 2021 17:11:30 -0700 Subject: [PATCH 8/8] Correct descriptions of Duration --- embassy/src/time/duration.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/embassy/src/time/duration.rs b/embassy/src/time/duration.rs index 38b0c0832..5157450ad 100644 --- a/embassy/src/time/duration.rs +++ b/embassy/src/time/duration.rs @@ -5,7 +5,7 @@ use super::TICKS_PER_SECOND; #[derive(Debug, Default, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] -/// Represents the difference between [Instant::now()](struct.Instant.html#method.now) and some other Instant +/// Represents the difference between two [Instant](struct.Instant.html)s pub struct Duration { pub(crate) ticks: u64, } @@ -68,14 +68,14 @@ impl Duration { .map(|ticks| Duration { ticks }) } - /// Multiplies one Duration to another, returning a new Duration or None in the event of an overflow. + /// Multiplies one Duration by a scalar u32, returning a new Duration or None in the event of an overflow. pub fn checked_mul(self, rhs: u32) -> Option<Duration> { self.ticks .checked_mul(rhs as _) .map(|ticks| Duration { ticks }) } - /// Divides one Duration against another, returning a new Duration or None in the event of an overflow. + /// Divides one Duration a scalar u32, returning a new Duration or None in the event of an overflow. pub fn checked_div(self, rhs: u32) -> Option<Duration> { self.ticks .checked_div(rhs as _)