Factor out 11-usart example code to included files

When running 'mdbook test' on the book the example code checking fails
to handle for example macros like '#[entry]' and the local auxiliary
crates. Having most code examples included from 'examples/' allows to
check them at least with 'cargo build --target thumbv7em-none-eabihf
--examples'.

Author: sirhcel

src/11-usart/buffer-overrun.md

@@ -3,25 +3,7 @@
 If you wrote your program like this:
 
 ``` rust
-#![no_main]
-#![no_std]
-
-#[allow(unused_imports)]
-use aux11::{entry, iprint, iprintln};
-
-#[entry]
-fn main() -> ! {
-    let (usart1, mono_timer, itm) = aux11::init();
-
-    // Send a string
-    for byte in b"The quick brown fox jumps over the lazy dog.".iter() {
-        usart1
-            .tdr
-            .write(|w| unsafe { w.tdr().bits(u16::from(*byte)) });
-    }
-
-    loop {}
-}
+{{#include examples/buffer-overrun.rs}}
 ```
 
 You probably received something like this on your computer when you executed the program compiled in
@@ -60,33 +42,7 @@ We can actually time how long it takes to execute the `for` loop. `aux11::init()
 `std::time`.
 
 ``` rust
-#![deny(unsafe_code)]
-#![no_main]
-#![no_std]
-
-#[allow(unused_imports)]
-use aux11::{entry, iprint, iprintln};
-
-#[entry]
-fn main() -> ! {
-    let (usart1, mono_timer, mut itm) = aux11::init();
-
-    let instant = mono_timer.now();
-    // Send a string
-    for byte in b"The quick brown fox jumps over the lazy dog.".iter() {
-        usart1.tdr.write(|w| w.tdr().bits(u16::from(*byte)));
-    }
-    let elapsed = instant.elapsed(); // in ticks
-
-    iprintln!(
-        &mut itm.stim[0],
-        "`for` loop took {} ticks ({} us)",
-        elapsed,
-        elapsed as f32 / mono_timer.frequency().0 as f32 * 1e6
-    );
-
-    loop {}
-}
+{{#include examples/buffer-overrun-timed.rs}}
 ```
 
 In debug mode, I get:
@@ -109,37 +65,7 @@ to write to the `TDR` register without incurring in data loss.
 Let's use that to slowdown the processor.
 
 ``` rust
-#![no_main]
-#![no_std]
-
-#[allow(unused_imports)]
-use aux11::{entry, iprint, iprintln};
-
-#[entry]
-fn main() -> ! {
-    let (usart1, mono_timer, mut itm) = aux11::init();
-
-    let instant = mono_timer.now();
-    // Send a string
-    for byte in b"The quick brown fox jumps over the lazy dog.".iter() {
-        // wait until it's safe to write to TDR
-        while usart1.isr.read().txe().bit_is_clear() {} // <- NEW!
-
-        usart1
-            .tdr
-            .write(|w| unsafe { w.tdr().bits(u16::from(*byte)) });
-    }
-    let elapsed = instant.elapsed(); // in ticks
-
-    iprintln!(
-        &mut itm.stim[0],
-        "`for` loop took {} ticks ({} us)",
-        elapsed,
-        elapsed as f32 / mono_timer.frequency().0 as f32 * 1e6
-    );
-
-    loop {}
-}
+{{#include examples/buffer-overrun-txe.rs}}
 ```
 
 This time, running the program in debug or release mode should result in a complete string on the

src/11-usart/examples/buffer-overrun-timed.rs

@@ -0,0 +1,27 @@
+#![deny(unsafe_code)]
+#![no_main]
+#![no_std]
+
+#[allow(unused_imports)]
+use aux11::{entry, iprint, iprintln};
+
+#[entry]
+fn main() -> ! {
+    let (usart1, mono_timer, mut itm) = aux11::init();
+
+    let instant = mono_timer.now();
+    // Send a string
+    for byte in b"The quick brown fox jumps over the lazy dog.".iter() {
+        usart1.tdr.write(|w| w.tdr().bits(u16::from(*byte)));
+    }
+    let elapsed = instant.elapsed(); // in ticks
+
+    iprintln!(
+        &mut itm.stim[0],
+        "`for` loop took {} ticks ({} us)",
+        elapsed,
+        elapsed as f32 / mono_timer.frequency().0 as f32 * 1e6
+    );
+
+    loop {}
+}

src/11-usart/examples/buffer-overrun-txe.rs

@@ -0,0 +1,31 @@
+#![no_main]
+#![no_std]
+
+#[allow(unused_imports)]
+use aux11::{entry, iprint, iprintln};
+
+#[entry]
+fn main() -> ! {
+    let (usart1, mono_timer, mut itm) = aux11::init();
+
+    let instant = mono_timer.now();
+    // Send a string
+    for byte in b"The quick brown fox jumps over the lazy dog.".iter() {
+        // wait until it's safe to write to TDR
+        while usart1.isr.read().txe().bit_is_clear() {} // <- NEW!
+
+        usart1
+            .tdr
+            .write(|w| unsafe { w.tdr().bits(u16::from(*byte)) });
+    }
+    let elapsed = instant.elapsed(); // in ticks
+
+    iprintln!(
+        &mut itm.stim[0],
+        "`for` loop took {} ticks ({} us)",
+        elapsed,
+        elapsed as f32 / mono_timer.frequency().0 as f32 * 1e6
+    );
+
+    loop {}
+}

src/11-usart/examples/buffer-overrun.rs

@@ -0,0 +1,19 @@
+#![no_main]
+#![no_std]
+
+#[allow(unused_imports)]
+use aux11::{entry, iprint, iprintln};
+
+#[entry]
+fn main() -> ! {
+    let (usart1, mono_timer, itm) = aux11::init();
+
+    // Send a string
+    for byte in b"The quick brown fox jumps over the lazy dog.".iter() {
+        usart1
+            .tdr
+            .write(|w| unsafe { w.tdr().bits(u16::from(*byte)) });
+    }
+
+    loop {}
+}

src/11-usart/examples/echo.rs

@@ -0,0 +1,48 @@
+#![no_main]
+#![no_std]
+
+#[allow(unused_imports)]
+use aux11::{entry, iprint, iprintln};
+use heapless::{consts, Vec};
+
+#[entry]
+fn main() -> ! {
+    let (usart1, mono_timer, itm) = aux11::init();
+
+    // A buffer with 32 bytes of capacity
+    let mut buffer: Vec<u8, consts::U32> = Vec::new();
+
+    loop {
+        buffer.clear();
+
+        loop {
+            while usart1.isr.read().rxne().bit_is_clear() {}
+            let byte = usart1.rdr.read().rdr().bits() as u8;
+
+            if buffer.push(byte).is_err() {
+                // buffer full
+                for byte in b"error: buffer full\n\r" {
+                    while usart1.isr.read().txe().bit_is_clear() {}
+                    usart1
+                        .tdr
+                        .write(|w| unsafe { w.tdr().bits(u16::from(*byte)) });
+                }
+
+                break;
+            }
+
+            // Carriage return
+            if byte == 13 {
+                // Respond
+                for byte in buffer.iter().rev().chain(&[b'\n', b'\r']) {
+                    while usart1.isr.read().txe().bit_is_clear() {}
+                    usart1
+                        .tdr
+                        .write(|w| unsafe { w.tdr().bits(u16::from(*byte)) });
+                }
+
+                break;
+            }
+        }
+    }
+}

src/11-usart/examples/receive-a-single-byte.rs

@@ -0,0 +1,21 @@
+#![deny(unsafe_code)]
+#![no_main]
+#![no_std]
+
+#[allow(unused_imports)]
+use aux11::{entry, iprint, iprintln};
+
+#[entry]
+fn main() -> ! {
+    let (usart1, mono_timer, itm) = aux11::init();
+
+    loop {
+        // Wait until there's data available
+        while usart1.isr.read().rxne().bit_is_clear() {}
+
+        // Retrieve the data
+        let _byte = usart1.rdr.read().rdr().bits() as u8;
+
+        aux11::bkpt();
+    }
+}

src/11-usart/examples/reverse-string.rs

@@ -0,0 +1,26 @@
+#![deny(unsafe_code)]
+#![no_main]
+#![no_std]
+
+#[allow(unused_imports)]
+use aux11::{entry, iprint, iprintln};
+use heapless::{consts, Vec};
+
+#[entry]
+fn main() -> ! {
+    let (usart1, mono_timer, itm) = aux11::init();
+
+    // A buffer with 32 bytes of capacity
+    let mut buffer: Vec<u8, consts::U32> = Vec::new();
+
+    loop {
+        buffer.clear();
+
+        // TODO Receive a user request. Each user request ends with ENTER
+        // NOTE `buffer.push` returns a `Result`. Handle the error by responding
+        // with an error message.
+
+        // TODO Send back the reversed string
+    }
+}
+

src/11-usart/examples/the-answer.rs

@@ -0,0 +1,46 @@
+#![deny(unsafe_code)]
+#![no_main]
+#![no_std]
+
+use core::fmt::{self, Write};
+
+#[allow(unused_imports)]
+use aux11::{entry, iprint, iprintln, usart1};
+
+macro_rules! uprint {
+    ($serial:expr, $($arg:tt)*) => {
+        $serial.write_fmt(format_args!($($arg)*)).ok()
+    };
+}
+
+macro_rules! uprintln {
+    ($serial:expr, $fmt:expr) => {
+        uprint!($serial, concat!($fmt, "\n"))
+    };
+    ($serial:expr, $fmt:expr, $($arg:tt)*) => {
+        uprint!($serial, concat!($fmt, "\n"), $($arg)*)
+    };
+}
+
+struct SerialPort {
+    usart1: &'static mut usart1::RegisterBlock,
+}
+
+impl fmt::Write for SerialPort {
+    fn write_str(&mut self, s: &str) -> fmt::Result {
+        // TODO implement this
+        // hint: this will look very similar to the previous program
+        Ok(())
+    }
+}
+
+#[entry]
+fn main() -> ! {
+    let (usart1, mono_timer, itm) = aux11::init();
+
+    let mut serial = SerialPort { usart1 };
+
+    uprintln!(serial, "The answer is {}", 40 + 2);
+
+    loop {}
+}

src/11-usart/my-solution.md

@@ -1,52 +1,5 @@
 # My solution
 
 ```rust
-#![no_main]
-#![no_std]
-
-#[allow(unused_imports)]
-use aux11::{entry, iprint, iprintln};
-use heapless::{consts, Vec};
-
-#[entry]
-fn main() -> ! {
-    let (usart1, mono_timer, itm) = aux11::init();
-
-    // A buffer with 32 bytes of capacity
-    let mut buffer: Vec<u8, consts::U32> = Vec::new();
-
-    loop {
-        buffer.clear();
-
-        loop {
-            while usart1.isr.read().rxne().bit_is_clear() {}
-            let byte = usart1.rdr.read().rdr().bits() as u8;
-
-            if buffer.push(byte).is_err() {
-                // buffer full
-                for byte in b"error: buffer full\n\r" {
-                    while usart1.isr.read().txe().bit_is_clear() {}
-                    usart1
-                        .tdr
-                        .write(|w| unsafe { w.tdr().bits(u16::from(*byte)) });
-                }
-
-                break;
-            }
-
-            // Carriage return
-            if byte == 13 {
-                // Respond
-                for byte in buffer.iter().rev().chain(&[b'\n', b'\r']) {
-                    while usart1.isr.read().txe().bit_is_clear() {}
-                    usart1
-                        .tdr
-                        .write(|w| unsafe { w.tdr().bits(u16::from(*byte)) });
-                }
-
-                break;
-            }
-        }
-    }
-}
+{{#include examples/echo.rs}}
 ```