From feebdb2c0b0cdc2afc7a51f740b4c01191505eb5 Mon Sep 17 00:00:00 2001
From: Jorge Aparicio <japaricious@gmail.com>
Date: Sat, 15 Apr 2017 09:38:08 -0500
Subject: [PATCH] more docs, sort examples

---
 README.md                                     | 14 ++++++++++
 examples/0-agnostic.rs                        | 15 +++++++++++
 examples/{hello.rs => 1-hello.rs}             |  4 +++
 examples/{itm.rs => 2-itm.rs}                 |  6 +++++
 ...on-override.rs => 3-exception-override.rs} |  2 ++
 examples/{srp.rs => 4-srp.rs}                 | 27 +++++++++++++++++--
 examples/minimal.rs                           | 17 ------------
 7 files changed, 66 insertions(+), 19 deletions(-)
 create mode 100644 examples/0-agnostic.rs
 rename examples/{hello.rs => 1-hello.rs} (70%)
 rename examples/{itm.rs => 2-itm.rs} (75%)
 rename examples/{exception-override.rs => 3-exception-override.rs} (88%)
 rename examples/{srp.rs => 4-srp.rs} (74%)
 delete mode 100644 examples/minimal.rs

diff --git a/README.md b/README.md
index 11f52e4..7597950 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,20 @@ $ cargo +nightly-2017-04-01 new stm32f100xx --template https://github.com/japari
 Where `stm32f100xx` is the name of the microcontroller family you are
 targeting.
 
+In the Cargo project, you'll have to update the `memory.x` file to reflect the
+memory layout of your device. For example, for the microcontroller in the
+[STM32VLDISCOVERY] which has 128 KB of Flash memory and 8 KB of RAM:
+
+[STM32VLDISCOVERY]: http://www.st.com/en/evaluation-tools/stm32vldiscovery.html
+
+```
+MEMORY
+{
+  FLASH : ORIGIN = 0x08000000, LENGTH = 128K
+  RAM : ORIGIN = 0x20000000, LENGTH = 8K
+}
+```
+
 ## Supported microcontroller families
 
 - nrf51
diff --git a/examples/0-agnostic.rs b/examples/0-agnostic.rs
new file mode 100644
index 0000000..198aa0c
--- /dev/null
+++ b/examples/0-agnostic.rs
@@ -0,0 +1,15 @@
+//! Device agnostic "Hello, world!"
+//!
+//! Prints "Hello, world!" on the OpenOCD console using semihosting
+
+#![feature(used)]
+#![no_std]
+
+extern crate cortex_m_rt;
+
+fn main() {}
+
+#[allow(dead_code)]
+#[used]
+#[link_section = ".rodata.interrupts"]
+static INTERRUPTS: [u32; 240] = [0; 240];
diff --git a/examples/hello.rs b/examples/1-hello.rs
similarity index 70%
rename from examples/hello.rs
rename to examples/1-hello.rs
index ea0910f..1473a76 100644
--- a/examples/hello.rs
+++ b/examples/1-hello.rs
@@ -1,3 +1,5 @@
+//! Device specific version of "Hello, world!"
+//!
 //! Prints "Hello, world!" on the OpenOCD console using semihosting
 
 #![feature(used)]
@@ -14,6 +16,8 @@ fn main() {
     hprintln!("Hello, world!");
 }
 
+// This is the device specific bit: properly populated interrupt handlers
+// Tough we are not using any of them in this example
 #[allow(dead_code)]
 #[used]
 #[link_section = ".rodata.interrupts"]
diff --git a/examples/itm.rs b/examples/2-itm.rs
similarity index 75%
rename from examples/itm.rs
rename to examples/2-itm.rs
index 40f66c5..643b4bc 100644
--- a/examples/itm.rs
+++ b/examples/2-itm.rs
@@ -1,5 +1,11 @@
 //! Sends "Hello, world!" through the ITM port 0
 //!
+//! **NOTE** Not all Cortex-M chips support ITM. You'll have to connect your
+//! microcontroller's SWO pin to the debug interface. Some development boards
+//! don't provide this option.
+//!
+//! This is faster than using semihosting.
+//!
 //! You'll need [`itmdump`] to receive the message plus you'll need to enable
 //! OpenOCD's ITM support in `.gdbinit`.
 //!
diff --git a/examples/exception-override.rs b/examples/3-exception-override.rs
similarity index 88%
rename from examples/exception-override.rs
rename to examples/3-exception-override.rs
index 2206329..b346b43 100644
--- a/examples/exception-override.rs
+++ b/examples/3-exception-override.rs
@@ -27,10 +27,12 @@ extern "C" fn hard_fault(_: exception::HardFault) {
     asm::bkpt()
 }
 
+// When the "exceptions" feature is disabled, you'll have to provide this symbol
 #[allow(dead_code)]
 #[used]
 #[link_section = ".rodata.exceptions"]
 static EXCEPTIONS: exception::Handlers = exception::Handlers {
+    // This is the exception handler override
     hard_fault: hard_fault,
     ..exception::DEFAULT_HANDLERS
 };
diff --git a/examples/srp.rs b/examples/4-srp.rs
similarity index 74%
rename from examples/srp.rs
rename to examples/4-srp.rs
index c39f1cc..439fe6f 100644
--- a/examples/srp.rs
+++ b/examples/4-srp.rs
@@ -1,3 +1,22 @@
+//! Stack Resource Policy
+//!
+//! You should see the following output
+//!
+//! ``` text
+//! IDLE
+//! J1: enter
+//! J2: enter
+//! J2(R1)
+//! J2: exit
+//! J1: after requesting J2
+//! J1(R1): before requesting J2
+//! J1(R1): after requesting J2
+//! J2: enter
+//! J2(R1)
+//! J2: exit
+//! J1: exit
+//! ```
+
 #![feature(const_fn)]
 #![feature(used)]
 #![no_std]
@@ -15,12 +34,16 @@ use {{name}}::interrupt::{Exti0Irq, Exti1Irq};
 static R1: Resource<(), C4> = Resource::new(());
 static R2: Resource<(), C2> = Resource::new(());
 
-fn init(_ceil: C16) {}
+fn init(_prio: P0, _ceil: C16) {}
 
-fn idle(_prio: P0) {
+fn idle(_prio: P0) -> ! {
     hprintln!("IDLE");
 
     rtfm::request(j1);
+
+    loop {
+        rtfm::wfi();
+    }
 }
 
 tasks!({{name}}, {
diff --git a/examples/minimal.rs b/examples/minimal.rs
deleted file mode 100644
index 39ef216..0000000
--- a/examples/minimal.rs
+++ /dev/null
@@ -1,17 +0,0 @@
-//! Minimal application
-
-#![feature(used)]
-#![no_std]
-
-extern crate cortex_m_rt;
-extern crate {{name}};
-
-use {{name}}::interrupt;
-
-fn main() {}
-
-#[allow(dead_code)]
-#[used]
-#[link_section = ".rodata.interrupts"]
-static INTERRUPTS: interrupt::Handlers =
-    interrupt::Handlers { ..interrupt::DEFAULT_HANDLERS };