From 9ca10b0d8c735a06a3a0a3623a7fc5d09b5e948c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= 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?= 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 From 71a279f6d0a2fa4f0e51d09eda47bd422a1b0240 Mon Sep 17 00:00:00 2001 From: Emil Fresk Date: Mon, 5 Oct 2020 20:38:52 +0200 Subject: Split up migration guides into its own sections --- book/en/src/migration.md | 333 +---------------------------------------------- 1 file changed, 3 insertions(+), 330 deletions(-) (limited to 'book/en/src/migration.md') diff --git a/book/en/src/migration.md b/book/en/src/migration.md index 7be3094..08feb81 100644 --- a/book/en/src/migration.md +++ b/book/en/src/migration.md @@ -1,331 +1,4 @@ -# Migration of RTIC +# Migration Guides -## 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] -} -``` - -### 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 -the version v0.5.0 of the framework. - -### `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 -version = "0.4.3" - -# into this -version = "0.5.0" - -# and remove this Cargo feature -features = ["timer-queue"] -# ^^^^^^^^^^^^^ -``` - -### `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 -magically injected into the scope of the function by version v0.4.x of the -framework: `resources`, `spawn`, `schedule` -- these variables will become -fields of the `Context` structure. Each function within the `#[rtic::app]` item -gets a different `Context` type. - -``` rust -#[rtic::app(/* .. */)] -const APP: () = { - // change this - #[task(resources = [x], spawn = [a], schedule = [b])] - fn foo() { - resources.x.lock(|x| /* .. */); - spawn.a(message); - schedule.b(baseline); - } - - // into this - #[task(resources = [x], spawn = [a], schedule = [b])] - fn foo(mut cx: foo::Context) { - // ^^^^^^^^^^^^^^^^^^^^ - - cx.resources.x.lock(|x| /* .. */); - // ^^^ - - cx.spawn.a(message); - // ^^^ - - cx.schedule.b(message, baseline); - // ^^^ - } - - // change this - #[init] - fn init() { - // .. - } - - // into this - #[init] - fn init(cx: init::Context) { - // ^^^^^^^^^^^^^^^^^ - // .. - } - - // .. -}; -``` - -### Resources - -The syntax used to declare resources has been changed from `static mut` -variables to a `struct Resources`. - -``` rust -#[rtic::app(/* .. */)] -const APP: () = { - // change this - static mut X: u32 = 0; - static mut Y: u32 = (); // late resource - - // into this - struct Resources { - #[init(0)] // <- initial value - X: u32, // NOTE: we suggest changing the naming style to `snake_case` - - Y: u32, // late resource - } - - // .. -}; -``` - -### 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 -`#[rtic::app]` attribute to continue to access the device peripherals through -the `device` field of the `init::Context` structure. - -Change this: - -``` rust -#[rtic::app(/* .. */)] -const APP: () = { - #[init] - fn init() { - device.SOME_PERIPHERAL.write(something); - } - - // .. -}; -``` - -Into this: - -``` rust -#[rtic::app(/* .. */, peripherals = true)] -// ^^^^^^^^^^^^^^^^^^ -const APP: () = { - #[init] - fn init(cx: init::Context) { - // ^^^^^^^^^^^^^^^^^ - cx.device.SOME_PERIPHERAL.write(something); - // ^^^ - } - - // .. -}; -``` - -### `#[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. - -Change this: - -``` rust -#[rtic::app(/* .. */)] -const APP: () = { - // hardware tasks - #[exception] - fn SVCall() { /* .. */ } - - #[interrupt] - fn UART0() { /* .. */ } - - // software task - #[task] - fn foo() { /* .. */ } - - // .. -}; -``` - -Into this: - -``` rust -#[rtic::app(/* .. */)] -const APP: () = { - #[task(binds = SVCall)] - // ^^^^^^^^^^^^^^ - fn svcall(cx: svcall::Context) { /* .. */ } - // ^^^^^^ we suggest you use a `snake_case` name here - - #[task(binds = UART0)] - // ^^^^^^^^^^^^^ - fn uart0(cx: uart0::Context) { /* .. */ } - - #[task] - fn foo(cx: foo::Context) { /* .. */ } - - // .. -}; -``` - -### `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` -argument of the `#[rtic::app]` attribute. To continue using the cycle counter -(CYCCNT) as the monotonic timer, and match the behavior of version v0.4.x, add -the `monotonic = rtic::cyccnt::CYCCNT` argument to the `#[rtic::app]` attribute. - -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`. - -Change this: - -``` rust -use rtic::{Duration, Instant, U32Ext}; - -#[rtic::app(/* .. */)] -const APP: () = { - #[task(schedule = [b])] - fn a() { - // .. - } -}; -``` - -Into this: - -``` rust -use rtic::cyccnt::{Duration, Instant, U32Ext}; -// ^^^^^^^^ - -#[rtic::app(/* .. */, monotonic = rtic::cyccnt::CYCCNT)] -// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -const APP: () = { - #[init] - fn init(cx: init::Context) { - cx.core.DWT.enable_cycle_counter(); - // optional, configure the DWT run without a debugger connected - cx.core.DCB.enable_trace(); - } - #[task(schedule = [b])] - fn a(cx: a::Context) { - // .. - } -}; -``` +This section describes how to migrate between different version of RTIC. +It also acts as a comparing reference between versions. -- cgit v1.2.3