Example documentation and cleanup.

rust-embedded · Jan 11, 2020 · 9405234 · 9405234
1 parent 0a5732d
commit 9405234
Show file tree

Hide file tree

Showing 5 changed files with 75 additions and 3 deletions.
diff --git a/examples/blinky.rs b/examples/blinky.rs
@@ -1,3 +1,11 @@
+//! Basic "hello world" blink demo for the [MSP-EXP430G2](http://www.ti.com/tool/MSP-EXP430G2)
+//! development kit using a software delay loop- in Rust!
+//!
+//! Although unnecessary for running the demo, this example also shows the syntax for declaring
+//! an interrupt.
+//!
+//! ---
+
 #![no_main]
 #![no_std]
 #![feature(abi_msp430_interrupt)]

diff --git a/examples/override-default-handler.rs b/examples/override-default-handler.rs
@@ -1,3 +1,15 @@
+//! Overriding the default interrupt handler with user code.
+//!
+//! The default handler is used for _any_ interrupts whose handler is not explicitly defined
+//! in the application. Normally an infinite loop, `DefaultHandler` can be overridden based on
+//! a user's needs.
+//!
+//! This demo is meant to more to be compiled and then examined with `msp430-elf-objdump` and
+//! other [binutils](https://www.gnu.org/software/binutils/) programs, rather than run on
+//! a development board.
+//!
+//! ---
+
 #![no_main]
 #![no_std]
 #![feature(abi_msp430_interrupt)]

diff --git a/examples/timer-oncecell.rs b/examples/timer-oncecell.rs
@@ -1,3 +1,31 @@
+//! Sharing data between a main thread and an interrupt handler safely.
+//!
+//! This example uses the externally-provided [once_cell][once] to safely share access to msp430
+//! peripherals between a main thread and interrupt.
+//!
+//! The different between [OnceCell][once] and [RefCell][ref] is that setting the data contained
+//! inside a [OnceCell][once] can be deferred to run time, but can only be set once. In contrast,
+//! the data contained within a [RefCell][ref] can be set multiple times throughout a program, but
+//! the contained data must be initialized at compile time. Additionally, [RefCell][ref] will
+//! panic if a second thread tries to change its value while the first thread is mutating the
+//! variable.
+//!
+//! The [Periperhals](msp430g2553::Peripherals) type, and individual peripherals never need
+//! to be modified. Therefore, [Periperhals](msp430g2553::Peripherals) (or a subset of the
+//! Periperhals _moved_ to another `struct`, if
+//! [building](https://blog.japaric.io/brave-new-io/#freezing-the-clock-configuration)
+//! higher-level abstractions) are good candidates to [`Send`](core::marker::Send) to a
+//! [OnceCell][once]. [OnceCell][once] in general seems to have better space usage than
+//! [RefCell][ref] due to its invariants.
+//!
+//! As with [timer] and [timer-unsafe], this example uses the `TIMER0_A1` interrupt to
+//! blink LEDs on the [MSP-EXP430G2](http://www.ti.com/tool/MSP-EXP430G2) development kit.
+//!
+//! [once]: once_cell::unsync::OnceCell
+//! [ref]: core::cell::RefCell
+//!
+//! ---
+
 #![no_main]
 #![no_std]
 #![feature(abi_msp430_interrupt)]

diff --git a/examples/timer-unsafe.rs b/examples/timer-unsafe.rs
@@ -1,3 +1,19 @@
+//! Sharing data between a main thread and an interrupt handler safely using `unsafe`
+//! code blocks in contexts where they can't cause
+//! (Undefined Behavior)[https://doc.rust-lang.org/reference/behavior-considered-undefined.html].
+//!
+//! This example uses the normally `unsafe`
+//! [`Peripherals::steal()`][steal] method to safely share access to msp430 peripherals between a
+//! main thread and interrupt. All uses of [`steal()`] are commented to explain _why_ its usage
+//! is safe in that particular context.
+//!
+//! As with [timer] and [timer-oncecell], this example uses the `TIMER0_A1` interrupt to blink
+//! LEDs on the [MSP-EXP430G2](http://www.ti.com/tool/MSP-EXP430G2) development kit.
+//!
+//! [steal]: msp430g2553::Peripherals::steal
+//!
+//! ---
+
 #![no_main]
 #![no_std]
 #![feature(abi_msp430_interrupt)]
@@ -44,9 +60,8 @@ fn main() -> ! {
 }
 
 #[interrupt]
-#[allow(unused_variables)]
 fn TIMER0_A1() {
-    mspint::free(|cs| {
+    mspint::free(|_cs| {
         // Safe because msp430 disables interrupts on handler entry. Therefore the handler
         // has full control/access to peripherals without data races.
         let p = unsafe { Peripherals::steal() };

diff --git a/examples/timer.rs b/examples/timer.rs
@@ -1,3 +1,13 @@
+//! Sharing data between a main thread and an interrupt handler safely.
+//!
+//! This example uses the [libcore](core)-provided [RefCell](core::cell::RefCell) to safely share
+//! access to msp430 peripherals between a main thread and interrupt.
+//!
+//! As with [timer-unsafe] and [timer-oncecell], this example uses the `TIMER0_A1` interrupt to
+//! blink LEDs on the [MSP-EXP430G2](http://www.ti.com/tool/MSP-EXP430G2) development kit.
+//!
+//! ---
+
 #![no_main]
 #![no_std]
 #![feature(abi_msp430_interrupt)]
@@ -51,7 +61,6 @@ fn main() -> ! {
 }
 
 #[interrupt]
-#[allow(unused_variables)]
 fn TIMER0_A1() {
     mspint::free(|cs| {
         let p_ref = PERIPHERALS.borrow(&cs).borrow();