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 <[email protected]>

Author: bors[bot]

.gitignore

@@ -5,3 +5,4 @@
 /target
 Cargo.lock
 *.hex
+book-target/

book/en/src/by-example/app_task.md renamed to book/en/archive/by_example/app_task.md

@@ -34,7 +34,7 @@ This activates the monotonics making it possible to use them.
 
 See the following example:
 
-``` rust
+``` rust,noplayground
 {{#include ../../../../examples/schedule.rs}}
 ```
 
@@ -54,7 +54,7 @@ which allows canceling or rescheduling of the task scheduled to run in the futur
 If `cancel` or `reschedule_at`/`reschedule_after` returns an `Err` it means that the operation was
 too late and that the task is already sent for execution. The following example shows this in action:
 
-``` rust
+``` rust,noplayground
 {{#include ../../../../examples/cancel-reschedule.rs}}
 ```
 

book/en/src/by-example/monotonic.md renamed to book/en/archive/by_example/monotonic.md

@@ -11,8 +11,8 @@ improve performance in some cases.
 
 The example below shows how to place the higher priority task, `bar`, in RAM.
 
-``` rust
-{{#include ../../../../rtic/examples/ramfunc.rs}}
+``` rust,noplayground
+{{#include ../../../../../rtic/examples/ramfunc.rs}}
 ```
 
 Running this program produces the expected output.
@@ -22,7 +22,7 @@ $ cargo run --target thumbv7m-none-eabi --example ramfunc
 ```
 
 ``` console
-{{#include ../../../../rtic/ci/expected/ramfunc.run}}
+{{#include ../../../../../rtic/ci/expected/ramfunc.run}}
 ```
 
 One can look at the output of `cargo-nm` to confirm that `bar` ended in RAM
@@ -33,13 +33,13 @@ $ cargo nm --example ramfunc --release | grep ' foo::'
 ```
 
 ``` console
-{{#include ../../../../rtic/ci/expected/ramfunc.run.grep.foo}}
+{{#include ../../../../../rtic/ci/expected/ramfunc.run.grep.foo}}
 ```
 
 ``` console
 $ cargo nm --example ramfunc  --target thumbv7m-none-eabi --release | grep '*bar::'
 ```
 
 ``` console
-{{#include ../../../../rtic/ci/expected/ramfunc.run.grep.bar}}
+{{#include ../../../../../rtic/ci/expected/ramfunc.run.grep.bar}}
 ```

book/en/src/by-example/tips_from_ram.md renamed to book/en/archive/by_example/tips/from_ram.md

@@ -27,7 +27,7 @@ cortex-m-rtic = "0.5.3"
 The only code change that needs to be made is that any reference to `rtfm` before now need to point
 to `rtic` as follows:
 
-``` rust
+``` rust,noplayground
 //
 // Change this
 //

book/en/src/migration.md renamed to book/en/archive/migration.md

@@ -42,7 +42,7 @@ framework: `resources`, `spawn`, `schedule` -- these variables will become
 fields of the `Context` structure. Each function within the `#[rtfm::app]` item
 gets a different `Context` type.
 
-``` rust
+``` rust,noplayground
 #[rtfm::app(/* .. */)]
 const APP: () = {
     // change this
@@ -90,7 +90,7 @@ const APP: () = {
 The syntax used to declare resources has changed from `static mut`
 variables to a `struct Resources`.
 
-``` rust
+``` rust,noplayground
 #[rtfm::app(/* .. */)]
 const APP: () = {
     // change this
@@ -118,7 +118,7 @@ the `device` field of the `init::Context` structure.
 
 Change this:
 
-``` rust
+``` rust,noplayground
 #[rtfm::app(/* .. */)]
 const APP: () = {
     #[init]
@@ -132,7 +132,7 @@ const APP: () = {
 
 Into this:
 
-``` rust
+``` rust,noplayground
 #[rtfm::app(/* .. */, peripherals = true)]
 //                    ^^^^^^^^^^^^^^^^^^
 const APP: () = {
@@ -155,7 +155,7 @@ attribute with the `binds` argument instead.
 
 Change this:
 
-``` rust
+``` rust,noplayground
 #[rtfm::app(/* .. */)]
 const APP: () = {
     // hardware tasks
@@ -175,7 +175,7 @@ const APP: () = {
 
 Into this:
 
-``` rust
+``` rust,noplayground
 #[rtfm::app(/* .. */)]
 const APP: () = {
     #[task(binds = SVCall)]
@@ -212,7 +212,7 @@ ensure it is enabled by the application inside `init`.
 
 Change this:
 
-``` rust
+``` rust,noplayground
 use rtfm::{Duration, Instant, U32Ext};
 
 #[rtfm::app(/* .. */)]
@@ -226,7 +226,7 @@ const APP: () = {
 
 Into this:
 
-``` rust
+``` rust,noplayground
 use rtfm::cyccnt::{Duration, Instant, U32Ext};
 //        ^^^^^^^^
 

book/en/src/migration/migration_rtic.md renamed to book/en/archive/migration/migration_rtic.md

@@ -12,7 +12,7 @@ With the support of attributes on modules the `const APP` workaround is not need
 
 Change
 
-``` rust
+``` rust,noplayground
 #[rtic::app(/* .. */)]
 const APP: () = {
   [code here]
@@ -21,7 +21,7 @@ const APP: () = {
 
 into
 
-``` rust
+``` rust,noplayground
 #[rtic::app(/* .. */)]
 mod app {
   [code here]
@@ -75,7 +75,7 @@ mod app {
 
 Change
 
-``` rust
+``` rust,noplayground
 #[rtic::app(/* .. */)]
 const APP: () = {
     [code here]
@@ -92,7 +92,7 @@ const APP: () = {
 
 into
 
-``` rust
+``` rust,noplayground
 #[rtic::app(/* .. */, dispatchers = [SSI0, QEI0])]
 mod app {
   [code here]
@@ -106,7 +106,7 @@ This works also for ram functions, see examples/ramfunc.rs
 
 Previously the RTIC resources had to be in in a struct named exactly "Resources":
 
-``` rust
+``` rust,noplayground
 struct Resources {
     // Resources defined in here
 }
@@ -115,7 +115,7 @@ struct Resources {
 With RTIC v1.0.0 the resources structs are annotated similarly like
 `#[task]`, `#[init]`, `#[idle]`: with the attributes `#[shared]` and `#[local]`
 
-``` rust
+``` rust,noplayground
 #[shared]
 struct MySharedResources {
     // Resources shared between tasks are defined here
@@ -136,7 +136,7 @@ In v1.0.0 resources are split between `shared` resources and `local` resources.
 
 In v0.5.x:
 
-``` rust
+``` rust,noplayground
 struct Resources {
     local_to_b: i64,
     shared_by_a_and_b: i64,
@@ -151,7 +151,7 @@ fn b(_: b::Context) {}
 
 In v1.0.0:
 
-``` rust
+``` rust,noplayground
 #[shared]
 struct Shared {
     shared_by_a_and_b: i64,
@@ -176,7 +176,7 @@ to be used for all `shared` resource access.
 In old code one could do the following as the high priority
 task has exclusive access to the resource:
 
-``` rust
+``` rust,noplayground
 #[task(priority = 2, resources = [r])]
 fn foo(cx: foo::Context) {
     cx.resources.r = /* ... */;
@@ -190,7 +190,7 @@ fn bar(cx: bar::Context) {
 
 And with symmetric locks one needs to use locks in both tasks:
 
-``` rust
+``` rust,noplayground
 #[task(priority = 2, shared = [r])]
 fn foo(cx: foo::Context) {
     cx.shared.r.lock(|r| r = /* ... */);
@@ -211,7 +211,7 @@ This is still possible in 1.0: the `#[shared]` resource must be annotated with t
 
 v0.5 code:
 
-``` rust
+``` rust,noplayground
 struct Resources {
     counter: u64,
 }
@@ -229,7 +229,7 @@ fn b(cx: b::Context) {
 
 v1.0 code:
 
-``` rust
+``` rust,noplayground
 #[shared]
 struct Shared {
     #[lock_free]
@@ -254,7 +254,7 @@ Instead of that syntax, use the `local` argument in `#[init]`.
 
 v0.5.x code:
 
-``` rust
+``` rust,noplayground
 #[init]
 fn init(_: init::Context) {
     static mut BUFFER: [u8; 1024] = [0; 1024];
@@ -264,7 +264,7 @@ fn init(_: init::Context) {
 
 v1.0.0 code:
 
-``` rust
+``` rust,noplayground
 #[init(local = [
     buffer: [u8; 1024] = [0; 1024]
 //   type ^^^^^^^^^^^^   ^^^^^^^^^ initial value
@@ -282,7 +282,7 @@ In order to make the API more symmetric the #[init]-task always returns a late r
 
 From this:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = lm3s6965)]
 const APP: () = {
     #[init]
@@ -296,7 +296,7 @@ const APP: () = {
 
 to this:
 
-``` rust
+``` rust,noplayground
 #[rtic::app(device = lm3s6965)]
 mod app {
     #[shared]
@@ -321,7 +321,7 @@ mod app {
 With the new spawn/spawn_after/spawn_at interface,
 old code requiring the context `cx` for spawning such as:
 
-``` rust
+``` rust,noplayground
 #[task(spawn = [bar])]
 fn foo(cx: foo::Context) {
     cx.spawn.bar().unwrap();
@@ -335,7 +335,7 @@ fn bar(cx: bar::Context) {
 
 Will now be written as:
 
-``` rust
+``` rust,noplayground
 #[task]
 fn foo(_c: foo::Context) {
     bar::spawn().unwrap();

book/en/src/migration/migration_v4.md renamed to book/en/archive/migration/migration_v4.md

@@ -2,31 +2,40 @@
 
 [Preface](./preface.md)
 
+---
+
+- [Starting a new project](./starting_a_project.md)
 - [RTIC by example](./by-example.md)
   - [The `app`](./by-example/app.md)
-  - [Hardware tasks & `pend`](./by-example/hardware_tasks.md)
+  - [Hardware tasks](./by-example/hardware_tasks.md)
   - [Software tasks & `spawn`](./by-example/software_tasks.md)
   - [Resources](./by-example/resources.md)
   - [The init task](./by-example/app_init.md)
   - [The idle task](./by-example/app_idle.md)
   - [Channel based communication](./by-example/channel.md)
-  - [Delay and Timeout](./by-example/delay.md)
-  - [Starting a new project](./by-example/starting_a_project.md)
+  - [Delay and Timeout using Monotonics](./by-example/delay.md)
   - [The minimal app](./by-example/app_minimal.md)
-  - [Tips & Tricks](./by-example/tips.md)
-    - [Implementing Monotonic](./by-example/tips_monotonic_impl.md)
-    - [Resource de-structure-ing](./by-example/tips_destructureing.md)
-    - [Avoid copies when message passing](./by-example/tips_indirection.md)
-    - [`'static` super-powers](./by-example/tips_static_lifetimes.md)
-    - [Inspecting generated code](./by-example/tips_view_code.md)
-    <!-- - [Running tasks from RAM](./by-example/tips_from_ram.md) -->
-    <!-- - [`#[cfg(..)]` support](./by-example/tips.md) -->
+  - [Tips & Tricks](./by-example/tips/index.md)
+    - [Resource de-structure-ing](./by-example/tips/destructureing.md)
+    - [Avoid copies when message passing](./by-example/tips/indirection.md)
+    - [`'static` super-powers](./by-example/tips/static_lifetimes.md)
+    - [Inspecting generated code](./by-example/tips/view_code.md)
+- [Monotonics & the Timer Queue](./monotonic_impl.md)
 - [RTIC vs. the world](./rtic_vs.md)
+- [RTIC and Embassy](./rtic_and_embassy.md)
 - [Awesome RTIC examples](./awesome_rtic.md)
-<!-- - [Migration Guides](./migration.md)
-  - [v0.5.x to v1.0.x](./migration/migration_v5.md)
-  - [v0.4.x to v0.5.x](./migration/migration_v4.md)
-  - [RTFM to RTIC](./migration/migration_rtic.md) -->
+
+---
+
+- [Migrating from v1.0.x to v2.0.0](./migration_v1_v2.md)
+  - [Rust Nightly & features](./migration_v1_v2/nightly.md)
+  - [Migrating to `rtic-monotonics`](./migration_v1_v2/monotonics.md)
+  - [Software tasks must now be `async`](./migration_v1_v2/async_tasks.md)
+  - [Using and understanding `rtic-sync`](./migration_v1_v2/rtic-sync.md)
+  - [A code example on migration](./migration_v1_v2/complete_example.md)
+
+---
+
 - [Under the hood](./internals.md)
   - [Cortex-M architectures](./internals/targets.md)
   <!--- [Interrupt configuration](./internals/interrupt-configuration.md)-->

book/en/src/migration/migration_v5.md renamed to book/en/archive/migration/migration_v5.md

@@ -1,8 +1,7 @@
 # Awesome RTIC examples
 
-See the [`rtic-rs/rtic-examples`][rticexamples] repository for community
-provided complete examples.
+See the [`rtic-rs/rtic/examples`][rticexamples] repository for complete examples.
 
-Pull-requests to this repo are welcome!
+Pull-requests are welcome!
 
-[rticexamples]: https://github.com/rtic-rs/rtic-examples
+[rticexamples]: https://github.com/rtic-rs/rtic/tree/master/examples