Add docs for BlockingTimer and rename tick features

2 files changed, 25 insertions, 18 deletions

diff --git a/embassy/Cargo.toml b/embassy/Cargo.toml
index f3cb46550..87f54409a 100644
--- a/embassy/Cargo.toml
+++ b/embassy/Cargo.toml
@@ -5,11 +5,11 @@ authors = ["Dario Nieuwenhuis <[email protected]>"]
 edition = "2018"
 
 [features]
-default = ["tick-hz-32768"]
+default = ["tick-32768hz"]
 std = ["futures/std", "embassy-traits/std"]
-tick-hz-32768 = []
-tick-hz-1000 = []
-tick-mhz-1 = []
+tick-32768hz = []
+tick-1000hz = []
+tick-1mhz = []
 
 defmt-trace = []
 defmt-debug = []
diff --git a/embassy/src/time/mod.rs b/embassy/src/time/mod.rs
index 2ebe19fbe..d50d9ef0d 100644
--- a/embassy/src/time/mod.rs
+++ b/embassy/src/time/mod.rs
@@ -11,20 +11,20 @@ pub use instant::Instant;
 pub use traits::*;
 
 #[cfg(any(
-    all(feature = "tick-hz-32768", feature = "tick-hz-1000"),
-    all(feature = "tick-hz-32768", feature = "tick-mhz-1"),
+    all(feature = "tick-32768hz", feature = "tick-1000hz"),
+    all(feature = "tick-32768hz", feature = "tick-1mhz"),
 ))]
 compile_error!(
     "Disable default-features to be able to use a tick rate other than the default (32768 Hz)"
 );
 
-#[cfg(feature = "tick-hz-1000")]
+#[cfg(feature = "tick-1000hz")]
 pub const TICKS_PER_SECOND: u64 = 1_000;
 
-#[cfg(feature = "tick-hz-32768")]
+#[cfg(feature = "tick-32768hz")]
 pub const TICKS_PER_SECOND: u64 = 32_768;
 
-#[cfg(feature = "tick-mhz-1")]
+#[cfg(feature = "tick-1mhz")]
 pub const TICKS_PER_SECOND: u64 = 1_000_000;
 
 static mut CLOCK: Option<&'static dyn Clock> = None;
@@ -43,47 +43,54 @@ pub(crate) fn now() -> u64 {
     unsafe { unwrap!(CLOCK, "No clock set").now() }
 }
 
+/// Type used for blocking delays through embedded-hal traits.
+///
+/// For this interface to work, the Executor's clock must be correctly initialized before using it.
+/// The delays are implemented in a "best-effort" way, meaning that the cpu will block for at least
+/// the amount provided, but accuracy can be affected by many factors, including interrupt usage.
+/// Make sure to use a suitable tick rate for your use case. The tick rate can be chosen through
+/// features flags of this crate.
 pub struct BlockingTimer;
 
 impl embedded_hal::blocking::delay::DelayMs<u8> for BlockingTimer {
     fn delay_ms(&mut self, ms: u8) {
-        block_for(Duration::from_millis(u64::from(ms)))
+        block_for(Duration::from_millis(ms as u64))
     }
 }
 
 impl embedded_hal::blocking::delay::DelayMs<u16> for BlockingTimer {
     fn delay_ms(&mut self, ms: u16) {
-        block_for(Duration::from_millis(u64::from(ms)))
+        block_for(Duration::from_millis(ms as u64))
     }
 }
 
 impl embedded_hal::blocking::delay::DelayMs<u32> for BlockingTimer {
     fn delay_ms(&mut self, ms: u32) {
-        block_for(Duration::from_millis(u64::from(ms)))
+        block_for(Duration::from_millis(ms as u64))
     }
 }
 
-#[cfg(feature = "tick-mhz-1")]
 impl embedded_hal::blocking::delay::DelayUs<u8> for BlockingTimer {
     fn delay_us(&mut self, us: u8) {
-        block_for(Duration::from_micros(u64::from(us)))
+        block_for(Duration::from_micros(us as u64))
     }
 }
 
-#[cfg(feature = "tick-mhz-1")]
 impl embedded_hal::blocking::delay::DelayUs<u16> for BlockingTimer {
     fn delay_us(&mut self, us: u16) {
-        block_for(Duration::from_micros(u64::from(us)))
+        block_for(Duration::from_micros(us as u64))
     }
 }
 
-#[cfg(feature = "tick-mhz-1")]
 impl embedded_hal::blocking::delay::DelayUs<u32> for BlockingTimer {
     fn delay_us(&mut self, us: u32) {
-        block_for(Duration::from_micros(u64::from(us)))
+        block_for(Duration::from_micros(us as u64))
     }
 }
 
+/// Blocks the cpu for at least `duration`.
+///
+/// For this interface to work, the Executor's clock must be correctly initialized before using it.
 pub fn block_for(duration: Duration) {
     let expires_at = Instant::now() + duration;
     while Instant::now() < expires_at {}