Merge #741

741: Docs 2 r=korken89 a=datdenkikniet

Working on the migration guide and other docs

TODO:
- [x] Migration guide
- [x] Hardcoded examples should link to example code that is tested (this was already done, AFAICT)
- [x] Address #699 
- [x] Discuss: should we remove references to non-v2, apart from the migration guide and link to the book for v1? (Off-github conclusion: yes)
- [x] RTIC {vs,and} Embassy (important: distinction between embassy runtime & HALs)
- [x] More descriptive docs on how to implement & PR implementations of `Monotonic` to `rtic-monotonics` 


Co-authored-by: datdenkikniet <jcdra1@gmail.com>

9 files changed, 32 insertions, 32 deletions

diff --git a/book/en/src/internals/access.md b/book/en/src/internals/access.md
index 3894470..b9cc621 100644
--- a/book/en/src/internals/access.md
+++ b/book/en/src/internals/access.md
@@ -27,7 +27,7 @@ section on [critical sections](critical-sections.html)).
 The code below is an example of the kind of source level transformation that
 happens behind the scenes:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = ..)]
 mod app {
     static mut X: u64: 0;
@@ -54,7 +54,7 @@ mod app {
 
 The framework produces codes like this:
 
-``` rust
+``` rust,noplayground
 fn init(c: init::Context) {
     // .. user code ..
 }
diff --git a/book/en/src/internals/ceilings.md b/book/en/src/internals/ceilings.md
index 07bd0ad..325e2ad 100644
--- a/book/en/src/internals/ceilings.md
+++ b/book/en/src/internals/ceilings.md
@@ -26,7 +26,7 @@ gets a unique reference (`&mut-`) to resources.
 
 An example to illustrate the ceiling analysis:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = ..)]
 mod app {
     struct Resources {
diff --git a/book/en/src/internals/critical-sections.md b/book/en/src/internals/critical-sections.md
index a064ad0..cd66c2b 100644
--- a/book/en/src/internals/critical-sections.md
+++ b/book/en/src/internals/critical-sections.md
@@ -30,7 +30,7 @@ task we give it a *resource proxy*, whereas we give a unique reference
 
 The example below shows the different types handed out to each task:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = ..)]
 mut app {
     struct Resources {
@@ -62,7 +62,7 @@ mut app {
 
 Now let's see how these types are created by the framework.
 
-``` rust
+``` rust,noplayground
 fn foo(c: foo::Context) {
     // .. user code ..
 }
@@ -149,7 +149,7 @@ The semantics of the `BASEPRI` register are as follows:
 
 Thus the dynamic priority at any point in time can be computed as
 
-``` rust
+``` rust,noplayground
 dynamic_priority = max(hw2logical(BASEPRI), hw2logical(static_priority))
 ```
 
@@ -160,7 +160,7 @@ In this particular example we could implement the critical section as follows:
 
 > **NOTE:** this is a simplified implementation
 
-``` rust
+``` rust,noplayground
 impl rtic::Mutex for resources::x {
     type T = u64;
 
@@ -194,7 +194,7 @@ calls to it. This is required for memory safety, as nested calls would produce
 multiple unique references (`&mut-`) to `x` breaking Rust aliasing rules. See
 below:
 
-``` rust
+``` rust,noplayground
 #[interrupt(binds = UART0, priority = 1, resources = [x])]
 fn foo(c: foo::Context) {
     // resource proxy
@@ -223,7 +223,7 @@ provides extra information to the compiler.
 
 Consider this program:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = ..)]
 mod app {
     struct Resources {
@@ -282,7 +282,7 @@ mod app {
 
 The code generated by the framework looks like this:
 
-``` rust
+``` rust,noplayground
 // omitted: user code
 
 pub mod resources {
@@ -374,7 +374,7 @@ mod app {
 At the end the compiler will optimize the function `foo` into something like
 this:
 
-``` rust
+``` rust,noplayground
 fn foo(c: foo::Context) {
     // NOTE: BASEPRI contains the value `0` (its reset value) at this point
 
@@ -428,7 +428,7 @@ should not result in an observable change of BASEPRI.
 This invariant needs to be preserved to avoid raising the dynamic priority of a
 handler through preemption. This is best observed in the following example:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = ..)]
 mod app {
     struct Resources {
@@ -490,7 +490,7 @@ mod app {
 IMPORTANT: let's say we *forget* to roll back `BASEPRI` in `UART1` -- this would
 be a bug in the RTIC code generator.
 
-``` rust
+``` rust,noplayground
 // code generated by RTIC
 
 mod app {
diff --git a/book/en/src/internals/interrupt-configuration.md b/book/en/src/internals/interrupt-configuration.md
index 7aec9c9..531c2bb 100644
--- a/book/en/src/internals/interrupt-configuration.md
+++ b/book/en/src/internals/interrupt-configuration.md
@@ -11,7 +11,7 @@ configuration is done before the `init` function runs.
 
 This example gives you an idea of the code that the RTIC framework runs:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = lm3s6965)]
 mod app {
     #[init]
@@ -33,7 +33,7 @@ mod app {
 
 The framework generates an entry point that looks like this:
 
-``` rust
+``` rust,noplayground
 // the real entry point of the program
 #[no_mangle]
 unsafe fn main() -> ! {
diff --git a/book/en/src/internals/late-resources.md b/book/en/src/internals/late-resources.md
index f3a0b0a..ce36756 100644
--- a/book/en/src/internals/late-resources.md
+++ b/book/en/src/internals/late-resources.md
@@ -8,7 +8,7 @@ interrupts are disabled.
 The example below shows the kind of code that the framework generates to
 initialize late resources.
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = ..)]
 mod app {
     struct Resources {
@@ -39,7 +39,7 @@ mod app {
 
 The code generated by the framework looks like this:
 
-``` rust
+``` rust,noplayground
 fn init(c: init::Context) -> init::LateResources {
     // .. user code ..
 }
diff --git a/book/en/src/internals/non-reentrancy.md b/book/en/src/internals/non-reentrancy.md
index 17b34d0..04785c3 100644
--- a/book/en/src/internals/non-reentrancy.md
+++ b/book/en/src/internals/non-reentrancy.md
@@ -10,7 +10,7 @@ To reenter a task handler in software its underlying interrupt handler must be
 invoked using FFI (see example below). FFI requires `unsafe` code so end users
 are discouraged from directly invoking an interrupt handler.
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = ..)]
 mod app {
     #[init]
@@ -48,7 +48,7 @@ call from user code.
 
 The above example expands into:
 
-``` rust
+``` rust,noplayground
 fn foo(c: foo::Context) {
     // .. user code ..
 }
diff --git a/book/en/src/internals/targets.md b/book/en/src/internals/targets.md
index 3562eef..67c6a59 100644
--- a/book/en/src/internals/targets.md
+++ b/book/en/src/internals/targets.md
@@ -29,7 +29,7 @@ Table 1 below shows a list of Cortex-m processors and which type of critical sec
 
 ## Priority Ceiling
 
-This is covered by the [Resources][resources] page of this book.
+This is covered by the [Resources](../by-example/resources.html) page of this book.
 
 ## Source Masking
 
diff --git a/book/en/src/internals/tasks.md b/book/en/src/internals/tasks.md
index db7afad..a58db8f 100644
--- a/book/en/src/internals/tasks.md
+++ b/book/en/src/internals/tasks.md
@@ -26,7 +26,7 @@ is treated as a resource contended by the tasks that can `spawn` other tasks.
 Let's first take a look the code generated by the framework to dispatch tasks.
 Consider this example:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = ..)]
 mod app {
     // ..
@@ -57,7 +57,7 @@ mod app {
 The framework produces the following task dispatcher which consists of an
 interrupt handler and a ready queue:
 
-``` rust
+``` rust,noplayground
 fn bar(c: bar::Context) {
     // .. user code ..
 }
@@ -121,7 +121,7 @@ There's one `Spawn` struct per task.
 The `Spawn` code generated by the framework for the previous example looks like
 this:
 
-``` rust
+``` rust,noplayground
 mod foo {
     // ..
 
@@ -206,7 +206,7 @@ task capacities.
 We have omitted how message passing actually works so let's revisit the `spawn`
 implementation but this time for task `baz` which receives a `u64` message.
 
-``` rust
+``` rust,noplayground
 fn baz(c: baz::Context, input: u64) {
     // .. user code ..
 }
@@ -268,7 +268,7 @@ mod app {
 
 And now let's look at the real implementation of the task dispatcher:
 
-``` rust
+``` rust,noplayground
 mod app {
     // ..
 
@@ -355,7 +355,7 @@ endpoint is owned by a task dispatcher.
 
 Consider the following example:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = ..)]
 mod app {
     #[idle(spawn = [foo, bar])]
diff --git a/book/en/src/internals/timer-queue.md b/book/en/src/internals/timer-queue.md
index fcd345c..06056e2 100644
--- a/book/en/src/internals/timer-queue.md
+++ b/book/en/src/internals/timer-queue.md
@@ -10,7 +10,7 @@ appropriate ready queue.
 
 Let's see how this in implemented in code. Consider the following program:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = ..)]
 mod app {
     // ..
@@ -31,7 +31,7 @@ mod app {
 
 Let's first look at the `schedule` API.
 
-``` rust
+``` rust,noplayground
 mod foo {
     pub struct Schedule<'a> {
         priority: &'a Cell<u8>,
@@ -122,7 +122,7 @@ is up.
 
 Let's see the associated code.
 
-``` rust
+``` rust,noplayground
 mod app {
     #[no_mangle]
     fn SysTick() {
@@ -220,7 +220,7 @@ analysis.
 
 To illustrate, consider the following example:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = ..)]
 mod app {
     #[task(priority = 3, spawn = [baz])]
@@ -269,7 +269,7 @@ an `INSTANTS` buffers used to store the time at which a task was scheduled to
 run; this `Instant` is read in the task dispatcher and passed to the user code
 as part of the task context.
 
-``` rust
+``` rust,noplayground
 mod app {
     // ..
 
@@ -311,7 +311,7 @@ buffer. The value to be written is stored in the `Spawn` struct and its either
 the `start` time of the hardware task or the `scheduled` time of the software
 task.
 
-``` rust
+``` rust,noplayground
 mod foo {
     // ..