Merge #255

255: more monotonic timer docs r=nils-grepit a=japaric

covers

- initialization and configuration of the timer; this is now a responsibility of
  the application author
- correctness of `Monotonic::now()` in `#[init]`
- safety of `Monotonic::reset()`

closes #251
cc @jonas-schievink

(EDIT: yay, pull request number 0xFF)

Co-authored-by: Jorge Aparicio <jorge@japaric.io>

3 files changed, 13 insertions, 3 deletions

diff --git a/examples/baseline.rs b/examples/baseline.rs
index b7144dd..df0ff9a 100644
--- a/examples/baseline.rs
+++ b/examples/baseline.rs
@@ -14,6 +14,8 @@ use panic_semihosting as _;
 const APP: () = {
     #[init(spawn = [foo])]
     fn init(cx: init::Context) {
+        // omitted: initialization of `CYCCNT`
+
         hprintln!("init(baseline = {:?})", cx.start).unwrap();
 
         // `foo` inherits the baseline of `init`: `Instant(0)`
diff --git a/examples/periodic.rs b/examples/periodic.rs
index ec110e1..dca0ad5 100644
--- a/examples/periodic.rs
+++ b/examples/periodic.rs
@@ -16,6 +16,8 @@ const PERIOD: u32 = 8_000_000;
 const APP: () = {
     #[init(schedule = [foo])]
     fn init(cx: init::Context) {
+        // omitted: initialization of `CYCCNT`
+
         cx.schedule.foo(Instant::now() + PERIOD.cycles()).unwrap();
     }
 
diff --git a/examples/schedule.rs b/examples/schedule.rs
index 27d3bd1..97818e3 100644
--- a/examples/schedule.rs
+++ b/examples/schedule.rs
@@ -1,6 +1,5 @@
 //! examples/schedule.rs
 
-#![deny(unsafe_code)]
 #![deny(warnings)]
 #![no_main]
 #![no_std]
@@ -13,8 +12,15 @@ use rtfm::cyccnt::{Instant, U32Ext as _};
 #[rtfm::app(device = lm3s6965, monotonic = rtfm::cyccnt::CYCCNT)]
 const APP: () = {
     #[init(schedule = [foo, bar])]
-    fn init(cx: init::Context) {
-        let now = Instant::now();
+    fn init(mut cx: init::Context) {
+        // Initialize (enable) the monotonic timer (CYCCNT)
+        cx.core.DCB.enable_trace();
+        // required on devices that software lock the DWT (e.g. STM32F7)
+        unsafe { cx.core.DWT.lar.write(0xC5ACCE55) }
+        cx.core.DWT.enable_cycle_counter();
+
+        // semantically, the monotonic timer is frozen at time "zero" during `init`
+        let now = cx.start; // the start time of the system
 
         hprintln!("init @ {:?}", now).unwrap();