fix included examples and markdown(book) (#912)

* fix included examples and markdown(book)

fixes: #911

* fix footnote pre_init

* more example link updates

* Restore pool example name

* Example: pool: Upgrade to heapless v0.8

* Example: pool: thumbv6 unsupported: wild cfg-if

Experiment with multi-backend example contained in the example

* Example: lm3s6965: Updated cargo.lock

* Book: Use cargo xtask for by-example

* Docs: Contributing: cargo xtask

---------

Co-authored-by: Henrik Tjäder <henrik@tjaders.com>

examples/lm3s6965/Cargo.lock

@@ -354,7 +354,7 @@ dependencies = [
 
 [[package]]
 name = "rtic"
-version = "2.1.0"
+version = "2.1.1"
 dependencies = [
  "atomic-polyfill",
  "bare-metal 1.0.0",
@@ -429,6 +429,7 @@ name = "rtic_lm3s6965"
 version = "0.1.0"
 dependencies = [
  "bare-metal 1.0.0",
+ "cfg-if",
  "cortex-m",
  "cortex-m-semihosting",
  "futures",

examples/lm3s6965/Cargo.toml

@@ -18,6 +18,7 @@ rtic-time = { path = "../../rtic-time" }
 rtic-sync = { path = "../../rtic-sync" }
 rtic-monotonics = { path = "../../rtic-monotonics", features = ["cortex-m-systick"] }
 rtic = { path = "../../rtic" }
+cfg-if = "1.0"
 
 [dependencies.futures]
 version = "0.3.26"

examples/lm3s6965/examples/pool.rs

@@ -0,0 +1,102 @@
+//! examples/pool.rs
+
+#![no_main]
+#![no_std]
+#![deny(warnings)]
+
+use panic_semihosting as _;
+use rtic::app;
+
+// thumbv6-none-eabi does not support pool
+// This might be better worked around in the build system,
+// but for proof of concept, let's try having one example
+// being different for different backends
+// https://docs.rs/heapless/0.8.0/heapless/pool/index.html#target-support
+cfg_if::cfg_if! {
+    if #[cfg(feature = "thumbv6-backend")] {
+        // Copy of the smallest.rs example
+        #[app(device = lm3s6965)]
+        mod app {
+            use cortex_m_semihosting::debug;
+
+            #[shared]
+            struct Shared {}
+
+            #[local]
+            struct Local {}
+
+            #[init]
+            fn init(_: init::Context) -> (Shared, Local) {
+                debug::exit(debug::EXIT_SUCCESS); // Exit QEMU simulator
+                (Shared {}, Local {})
+            }
+        }
+    } else {
+        // Run actual pool example
+        use heapless::{
+            box_pool,
+            pool::boxed::{Box, BoxBlock},
+        };
+
+        // Declare a pool containing 8-byte memory blocks
+        box_pool!(P: u8);
+
+        const POOL_CAPACITY: usize = 512;
+
+        #[app(device = lm3s6965, dispatchers = [SSI0, QEI0])]
+        mod app {
+            use crate::{Box, BoxBlock, POOL_CAPACITY};
+            use cortex_m_semihosting::debug;
+            use lm3s6965::Interrupt;
+
+            // Import the memory pool into scope
+            use crate::P;
+
+            #[shared]
+            struct Shared {}
+
+            #[local]
+            struct Local {}
+
+            const BLOCK: BoxBlock<u8> = BoxBlock::new();
+
+            #[init(local = [memory: [BoxBlock<u8>; POOL_CAPACITY] = [BLOCK; POOL_CAPACITY]])]
+            fn init(cx: init::Context) -> (Shared, Local) {
+                for block in cx.local.memory {
+                    // Give the 'static memory to the pool
+                    P.manage(block);
+                }
+
+                rtic::pend(Interrupt::I2C0);
+
+                (Shared {}, Local {})
+            }
+
+            #[task(binds = I2C0, priority = 2)]
+            fn i2c0(_: i2c0::Context) {
+                // Claim 128 u8 blocks
+                let x = P.alloc(128).unwrap();
+
+                // .. send it to the `foo` task
+                foo::spawn(x).ok().unwrap();
+
+                // send another 128 u8 blocks to the task `bar`
+                bar::spawn(P.alloc(128).unwrap()).ok().unwrap();
+            }
+
+            #[task]
+            async fn foo(_: foo::Context, _x: Box<P>) {
+                // explicitly return the block to the pool
+                drop(_x);
+
+                debug::exit(debug::EXIT_SUCCESS); // Exit QEMU simulator
+            }
+
+            #[task(priority = 2)]
+            async fn bar(_: bar::Context, _x: Box<P>) {
+                // this is done automatically so we can omit the call to `drop`
+                // drop(_x);
+            }
+        }
+    }
+}

examples/lm3s6965/examples/pool.rs_old

@@ -1,69 +0,0 @@
-//! examples/pool.rs
-
-#![no_main]
-#![no_std]
-#![deny(warnings)]
-
-use heapless::{
-    pool,
-    pool::singleton::{Box, Pool},
-};
-use panic_semihosting as _;
-use rtic::app;
-
-// Declare a pool of 128-byte memory blocks
-pool!(P: [u8; 128]);
-
-#[app(device = lm3s6965, dispatchers = [SSI0, QEI0])]
-mod app {
-    use crate::{Box, Pool};
-    use cortex_m_semihosting::debug;
-    use lm3s6965::Interrupt;
-
-    // Import the memory pool into scope
-    use super::P;
-
-    #[shared]
-    struct Shared {}
-
-    #[local]
-    struct Local {}
-
-    #[init(local = [memory: [u8; 512] = [0; 512]])]
-    fn init(cx: init::Context) -> (Shared, Local) {
-        // Increase the capacity of the memory pool by ~4
-        P::grow(cx.local.memory);
-
-        rtic::pend(Interrupt::I2C0);
-
-        (Shared {}, Local {})
-    }
-
-    #[task(binds = I2C0, priority = 2)]
-    fn i2c0(_: i2c0::Context) {
-        // claim a memory block, initialize it and ..
-        let x = P::alloc().unwrap().init([0u8; 128]);
-
-        // .. send it to the `foo` task
-        foo::spawn(x).ok().unwrap();
-
-        // send another block to the task `bar`
-        bar::spawn(P::alloc().unwrap().init([0u8; 128]))
-            .ok()
-            .unwrap();
-    }
-
-    #[task]
-    async fn foo(_: foo::Context, _x: Box<P>) {
-        // explicitly return the block to the pool
-        drop(_x);
-
-        debug::exit(debug::EXIT_SUCCESS); // Exit QEMU simulator
-    }
-
-    #[task(priority = 2)]
-    async fn bar(_: bar::Context, _x: Box<P>) {
-        // this is done automatically so we can omit the call to `drop`
-        // drop(_x);
-    }
-}