more docs, sort examples

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

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];

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"]

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`.
 //!

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
 };

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}}, {

examples/minimal.rs

@@ -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 };