From 9ca10b0d8c735a06a3a0a3623a7fc5d09b5e948c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= <henrik@tjaders.com>
Date: Fri, 2 Oct 2020 09:33:28 +0000
Subject: Add migration to 0.6 along with updated documentation

---
 book/en/src/migration.md | 85 +++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 76 insertions(+), 9 deletions(-)

(limited to 'book/en/src/migration.md')

diff --git a/book/en/src/migration.md b/book/en/src/migration.md
index 6cca64d..ab45c29 100644
--- a/book/en/src/migration.md
+++ b/book/en/src/migration.md
@@ -1,14 +1,81 @@
-# Migrating from v0.4.x to v0.5.0
+# Migration of RTIC
+
+## Migrating from v0.5.x to v0.6.0
+
+This section describes how to upgrade from v0.5.x to v0.6.0 of the RTIC framework.
+
+### `Cargo.toml` - version bump
+
+Change the version of `cortex-m-rtic` to `"0.6.0"`.
+
+### Module instead of Const
+
+With the support of attributes on modules the `const APP` workaround is not needed.
+
+Change
+
+``` rust
+#[rtic::app(/* .. */)]
+const APP: () = {
+  [code here]
+};
+```
+
+into
+
+``` rust
+#[rtic::app(/* .. */)]
+mod app {
+  [code here]
+}
+```
+
+Now that a regular Rust module is used it means it is possible to have custom
+user code within that module.
+Additionally, it means that `use`-statements for resources etc may be required.
+
+### Init always returns late resources
+
+In order to make the API more symmetric the #[init]-task always returns a late resource.
+
+From this:
+
+``` rust
+#[rtic::app(device = lm3s6965)]
+mod app {
+    #[init]
+    fn init(_: init::Context) {
+        rtic::pend(Interrupt::UART0);
+    }
+    [more code]
+}
+```
+
+to this:
+
+``` rust
+#[rtic::app(device = lm3s6965)]
+mod app {
+    #[init]
+    fn init(_: init::Context) -> init::LateResources {
+        rtic::pend(Interrupt::UART0);
+
+        init::LateResources {}
+    }
+    [more code]
+}
+```
+
+## Migrating from v0.4.x to v0.5.0
 
 This section covers how to upgrade an application written against RTIC v0.4.x to
 the version v0.5.0 of the framework.
 
-## `Cargo.toml`
+### `Cargo.toml`
 
 First, the version of the `cortex-m-rtic` dependency needs to be updated to
 `"0.5.0"`. The `timer-queue` feature needs to be removed.
 
-
 ``` toml
 [dependencies.cortex-m-rtic]
 # change this
@@ -22,7 +89,7 @@ features = ["timer-queue"]
 #           ^^^^^^^^^^^^^
 ```
 
-## `Context` argument
+### `Context` argument
 
 All functions inside the `#[rtic::app]` item need to take as first argument a
 `Context` structure. This `Context` type will contain the variables that were
@@ -74,7 +141,7 @@ const APP: () = {
 };
 ```
 
-## Resources
+### Resources
 
 The syntax used to declare resources has been changed from `static mut`
 variables to a `struct Resources`.
@@ -98,7 +165,7 @@ const APP: () = {
 };
 ```
 
-## Device peripherals
+### Device peripherals
 
 If your application was accessing the device peripherals in `#[init]` through
 the `device` variable then you'll need to add `peripherals = true` to the
@@ -136,7 +203,7 @@ const APP: () = {
 };
 ```
 
-## `#[interrupt]` and `#[exception]`
+### `#[interrupt]` and `#[exception]`
 
 The `#[interrupt]` and `#[exception]` attributes have been removed. To declare
 hardware tasks in v0.5.x use the `#[task]` attribute with the `binds` argument.
@@ -182,7 +249,7 @@ const APP: () = {
 };
 ```
 
-## `schedule`
+### `schedule`
 
 The `timer-queue` feature has been removed. To use the `schedule` API one must
 first define the monotonic timer the runtime will use using the `monotonic`
@@ -194,7 +261,7 @@ Also, the `Duration` and `Instant` types and the `U32Ext` trait have been moved
 into the `rtic::cyccnt` module. This module is only available on ARMv7-M+
 devices. The removal of the `timer-queue` also brings back the `DWT` peripheral
 inside the core peripherals struct, this will need to be enabled by the application
-inside `init`. 
+inside `init`.
 
 Change this:
 
-- 
cgit v1.2.3


From 1482a251867bfb31708e8c7273db4bee1e67df36 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= <henrik@tjaders.com>
Date: Fri, 2 Oct 2020 09:55:25 +0000
Subject: Describe the resource struct attribute migration steps

---
 book/en/src/migration.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

(limited to 'book/en/src/migration.md')

diff --git a/book/en/src/migration.md b/book/en/src/migration.md
index ab45c29..7be3094 100644
--- a/book/en/src/migration.md
+++ b/book/en/src/migration.md
@@ -66,6 +66,37 @@ mod app {
 }
 ```
 
+### Resources struct - #[resources]
+
+Previously the RTIC resources had to be in in a struct named exactly "Resources":
+
+``` rust
+struct Resources {
+    // Resources defined in here
+}
+```
+
+With RTIC v0.6.0 the resources struct is annotated similarly like
+`#[task]`, `#[init]`, `#[idle]`: with an attribute `#[resources]`
+
+``` rust
+#[resources]
+struct Resources {
+    // Resources defined in here
+}
+```
+
+In fact, the name of the struct is now up to the developer:
+
+``` rust
+#[resources]
+struct whateveryouwant {
+    // Resources defined in here
+}
+```
+
+would work equally well.
+
 ## Migrating from v0.4.x to v0.5.0
 
 This section covers how to upgrade an application written against RTIC v0.4.x to
-- 
cgit v1.2.3