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>

5 files changed, 251 insertions, 0 deletions

diff --git a/book/en/src/migration_v1_v2/async_tasks.md b/book/en/src/migration_v1_v2/async_tasks.md
new file mode 100644
index 0000000..60f7033
--- /dev/null
+++ b/book/en/src/migration_v1_v2/async_tasks.md
@@ -0,0 +1,55 @@
+# Using `async` softare tasks.
+
+There have been a few changes to software tasks. They are outlined below.
+
+### Software tasks must now be `async`.
+
+All software tasks are now required to be `async`.
+
+#### Required changes.
+
+All of the tasks in your project that do not bind to an interrupt must now be an `async fn`. For example:
+
+``` rust,noplayground
+#[task(
+    local = [ some_resource ],
+    shared = [ my_shared_resource ],
+    priority = 2
+)]
+fn my_task(cx: my_task::Context) {
+    cx.local.some_resource.do_trick();
+    cx.shared.my_shared_resource.lock(|s| s.do_shared_thing());
+}
+```
+
+becomes
+
+``` rust,noplayground
+#[task(
+    local = [ some_resource ],
+    shared = [ my_shared_resource ],
+    priority = 2
+)]
+async fn my_task(cx: my_task::Context) {
+    cx.local.some_resource.do_trick();
+    cx.shared.my_shared_resource.lock(|s| s.do_shared_thing());
+}
+```
+
+## Software tasks may now run forever
+
+The new `async` software tasks are allowed to run forever, on one precondition: **there must be an `await` within the infinite loop of the task**. An example of such a task:
+
+``` rust,noplayground
+#[task(local = [ my_channel ] )]
+async fn my_task_that_runs_forever(cx: my_task_that_runs_forever::Context) {
+    loop {
+        let value = cx.local.my_channel.recv().await;
+        do_something_with_value(value);
+    }
+}
+```
+
+## `spawn_after` and `spawn_at` have been removed.
+
+As discussed in the [Migrating to `rtic-monotonics`](./monotonics.md) chapter, `spawn_after` and `spawn_at` are no longer available.
\ No newline at end of file
diff --git a/book/en/src/migration_v1_v2/complete_example.md b/book/en/src/migration_v1_v2/complete_example.md
new file mode 100644
index 0000000..19a746a
--- /dev/null
+++ b/book/en/src/migration_v1_v2/complete_example.md
@@ -0,0 +1,169 @@
+# A complete example of migration
+
+Below you can find the code for the implementation of the `stm32f3_blinky` example for v1.0.x and for v2.0.0. Further down, a diff is displayed.
+
+# v1.0.X
+
+```rust
+#![deny(unsafe_code)]
+#![deny(warnings)]
+#![no_main]
+#![no_std]
+
+use panic_rtt_target as _;
+use rtic::app;
+use rtt_target::{rprintln, rtt_init_print};
+use stm32f3xx_hal::gpio::{Output, PushPull, PA5};
+use stm32f3xx_hal::prelude::*;
+use systick_monotonic::{fugit::Duration, Systick};
+
+#[app(device = stm32f3xx_hal::pac, peripherals = true, dispatchers = [SPI1])]
+mod app {
+    use super::*;
+
+    #[shared]
+    struct Shared {}
+
+    #[local]
+    struct Local {
+        led: PA5<Output<PushPull>>,
+        state: bool,
+    }
+
+    #[monotonic(binds = SysTick, default = true)]
+    type MonoTimer = Systick<1000>;
+
+    #[init]
+    fn init(cx: init::Context) -> (Shared, Local, init::Monotonics) {
+        // Setup clocks
+        let mut flash = cx.device.FLASH.constrain();
+        let mut rcc = cx.device.RCC.constrain();
+
+        let mono = Systick::new(cx.core.SYST, 36_000_000);
+
+        rtt_init_print!();
+        rprintln!("init");
+
+        let _clocks = rcc
+            .cfgr
+            .use_hse(8.MHz())
+            .sysclk(36.MHz())
+            .pclk1(36.MHz())
+            .freeze(&mut flash.acr);
+
+        // Setup LED
+        let mut gpioa = cx.device.GPIOA.split(&mut rcc.ahb);
+        let mut led = gpioa
+            .pa5
+            .into_push_pull_output(&mut gpioa.moder, &mut gpioa.otyper);
+        led.set_high().unwrap();
+
+        // Schedule the blinking task
+        blink::spawn_after(Duration::<u64, 1, 1000>::from_ticks(1000)).unwrap();
+
+        (
+            Shared {},
+            Local { led, state: false },
+            init::Monotonics(mono),
+        )
+    }
+
+    #[task(local = [led, state])]
+    fn blink(cx: blink::Context) {
+        rprintln!("blink");
+        if *cx.local.state {
+            cx.local.led.set_high().unwrap();
+            *cx.local.state = false;
+        } else {
+            cx.local.led.set_low().unwrap();
+            *cx.local.state = true;
+        }
+        blink::spawn_after(Duration::<u64, 1, 1000>::from_ticks(1000)).unwrap();
+    }
+}
+
+```
+
+# V2.0.0
+
+``` rust,noplayground
+{{ #include ../../../../examples/stm32f3_blinky/src/main.rs }}
+```
+
+## A diff between the two projects
+
+_Note_: This diff may not be 100% accurate, but it displays the important changes.
+
+``` diff
+#![no_main]
+ #![no_std]
++#![feature(type_alias_impl_trait)]
+ 
+ use panic_rtt_target as _;
+ use rtic::app;
+ use stm32f3xx_hal::gpio::{Output, PushPull, PA5};
+ use stm32f3xx_hal::prelude::*;
+-use systick_monotonic::{fugit::Duration, Systick};
++use rtic_monotonics::Systick;
+ 
+ #[app(device = stm32f3xx_hal::pac, peripherals = true, dispatchers = [SPI1])]
+ mod app {
+@@ -20,16 +21,14 @@ mod app {
+         state: bool,
+     }
+ 
+-    #[monotonic(binds = SysTick, default = true)]
+-    type MonoTimer = Systick<1000>;
+-
+     #[init]
+     fn init(cx: init::Context) -> (Shared, Local, init::Monotonics) {
+         // Setup clocks
+         let mut flash = cx.device.FLASH.constrain();
+         let mut rcc = cx.device.RCC.constrain();
+ 
+-        let mono = Systick::new(cx.core.SYST, 36_000_000);
++        let mono_token = rtic_monotonics::create_systick_token!();
++        let mono = Systick::new(cx.core.SYST, 36_000_000, mono_token);
+ 
+         let _clocks = rcc
+             .cfgr
+@@ -46,7 +45,7 @@ mod app {
+         led.set_high().unwrap();
+ 
+         // Schedule the blinking task
+-        blink::spawn_after(Duration::<u64, 1, 1000>::from_ticks(1000)).unwrap();
++        blink::spawn().unwrap();
+ 
+         (
+             Shared {},
+@@ -56,14 +55,18 @@ mod app {
+     }
+ 
+     #[task(local = [led, state])]
+-    fn blink(cx: blink::Context) {
+-        rprintln!("blink");
+-        if *cx.local.state {
+-            cx.local.led.set_high().unwrap();
+-            *cx.local.state = false;
+-        } else {
+-            cx.local.led.set_low().unwrap();
+-            *cx.local.state = true;
+-        blink::spawn_after(Duration::<u64, 1, 1000>::from_ticks(1000)).unwrap();
+-    }
++    async fn blink(cx: blink::Context) {
++        loop {
++            // A task is now allowed to run forever, provided that
++            // there is an `await` somewhere in the loop.
++            SysTick::delay(1000.millis()).await;
++            rprintln!("blink");
++            if *cx.local.state {
++                cx.local.led.set_high().unwrap();
++                *cx.local.state = false;
++            } else {
++                cx.local.led.set_low().unwrap();
++                *cx.local.state = true;
++            }
++        }
++    }
+ }
+```
\ No newline at end of file
diff --git a/book/en/src/migration_v1_v2/monotonics.md b/book/en/src/migration_v1_v2/monotonics.md
new file mode 100644
index 0000000..a8b0dba
--- /dev/null
+++ b/book/en/src/migration_v1_v2/monotonics.md
@@ -0,0 +1,13 @@
+# Migrating to `rtic-monotonics`
+
+In previous versions of `rtic`, monotonics were an integral, tightly coupled part of the `#[rtic::app]`. In this new version, [`rtic-monotonics`] provides them in a more decoupled way.
+
+The `#[monotonic]` attribute is no longer used. Instead, you use a `create_X_token` from [`rtic-monotonics`]. An invocation of this macro returns an interrupt registration token, which can be used to construct an instance of your desired monotonic.
+
+`spawn_after` and `spawn_at` are no longer available. Instead, you use the async functions `delay` and `delay_until` provided by ipmlementations of the `rtic_time::Monotonic` trait, available through [`rtic-monotonics`].
+
+Check out the [code example](./complete_example.md) for an overview of the required changes.
+
+For more information on current monotonic implementations, see [the `rtic-monotonics` documentation](https://docs.rs/rtic-monotonics), and [the examples](https://github.com/rtic-rs/rtic/tree/master/examples).
+
+[`rtic-monotonics`]: ghttps://github.com/rtic/rtic-monotonics
\ No newline at end of file
diff --git a/book/en/src/migration_v1_v2/nightly.md b/book/en/src/migration_v1_v2/nightly.md
new file mode 100644
index 0000000..09f6e33
--- /dev/null
+++ b/book/en/src/migration_v1_v2/nightly.md
@@ -0,0 +1,5 @@
+# RTIC now requires Rust Nightly
+
+The new `async` features require that you use a nightly compiler, and that the feature `type_alias_impl_trait` is enabled for your applications.
+
+To enable this feature, you must add the line `#![type_alias_impl_trait]` to the root file of your project, on the lines below or above where `#![no_std]` and `#![no_main]` are defined.
\ No newline at end of file
diff --git a/book/en/src/migration_v1_v2/rtic-sync.md b/book/en/src/migration_v1_v2/rtic-sync.md
new file mode 100644
index 0000000..fefde03
--- /dev/null
+++ b/book/en/src/migration_v1_v2/rtic-sync.md
@@ -0,0 +1,9 @@
+# Using `rtic-sync`
+
+`rtic-sync` provides primitives that can be used for message passing and resource sharing in async context.
+
+The important structs are:
+* The `Arbiter`, which allows you to await access to a shared resource in async contexts without using `lock`.
+* `Channel`, which allows you to communicate between tasks (both `async` and non-`async`).
+
+For more information on these structs, see the [`rtic-sync` docs](https://docs.rs/rtic-sync)
\ No newline at end of file