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>

1 files changed, 55 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