From 66a1993f5d6ee266325c4b40ecd35e05a5cf6aa1 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Wed, 16 Oct 2019 14:39:02 -0500 Subject: [PATCH 1/2] add migration guide --- book/en/src/SUMMARY.md | 1 + book/en/src/migration.md | 225 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 226 insertions(+) create mode 100644 book/en/src/migration.md diff --git a/book/en/src/SUMMARY.md b/book/en/src/SUMMARY.md index 8b62633688..3d5a4f8e69 100644 --- a/book/en/src/SUMMARY.md +++ b/book/en/src/SUMMARY.md @@ -9,6 +9,7 @@ - [Types, Send and Sync](./by-example/types-send-sync.md) - [Starting a new project](./by-example/new.md) - [Tips & tricks](./by-example/tips.md) +- [Migrating from v0.4.x to v0.5.0](./migration.md) - [Under the hood](./internals.md) - [Interrupt configuration](./internals/interrupt-configuration.md) - [Non-reentrancy](./internals/non-reentrancy.md) diff --git a/book/en/src/migration.md b/book/en/src/migration.md new file mode 100644 index 0000000000..5e2f86575c --- /dev/null +++ b/book/en/src/migration.md @@ -0,0 +1,225 @@ +# Migrating from v0.4.x to v0.5.0 + +This section covers how to upgrade an application written against RTFM v0.4.x to +the version v0.5.0 of the framework. + +## `Cargo.toml` + +First, the version of the `cortex-m-rtfm` dependency needs to be updated to +`"0.5.0"`. The `timer-queue` feature needs to be removed. + + +``` toml +[dependencies.cortex-m-rtfm] +# 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 `#[rtfm::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 `#[rtfm::app]` item +gets a different `Context` type. + +``` rust +#[rtfm::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 +#[rtfm::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 +`#[rtfm::app]` attribute to continue to access the device peripherals through +the `device` field of the `init::Context` structure. + +Change this: + +``` rust +#[rtfm::app(/* .. */)] +const APP: () = { + #[init] + fn init() { + peripherals.SOME_PERIPHERAL.write(something); + } + + // .. +}; +``` + +Into this: + +``` rust +#[rtfm::app(/* .. */, peripherals = true)] +// ^^^^^^^^^^^^^^^^^^ +const APP: () = { + #[init] + fn init(cx: init::Context) { + // ^^^^^^^^^^^^^^^^^ + cx.peripherals.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 +#[rtfm::app(/* .. */)] +const APP: () = { + // hardware tasks + #[exception] + fn SVCall() { /* .. */ } + + #[interrupt] + fn UART0() { /* .. */ } + + // software task + #[task] + fn foo() { /* .. */ } + + // .. +}; +``` + +Into this: + +``` rust +#[rtfm::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 `#[rtfm::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 = rtfm::cyccnt::CYCCNT` argument to the `#[rtfm::app]` attribute. + +Also, the `Duration` and `Instant` types and the `U32Ext` trait have been moved +into the `rtfm::cyccnt` module. This module is only available on ARMv7-M +devices. + +Change this: + +``` rust +use rtfm::{Duration, Instant, U32Ext}; + +#[rtfm::app(/* .. */)] +const APP: () = { + #[task(schedule = [b])] + fn a() { + // .. + } +}; +``` + +Into this: + +``` rust +use rtfm::cyccnt::{Duration, Instant, U32Ext}; +// ^^^^^^^^ + +#[rtfm::app(/* .. */, monotonic = rtfm::cyccnt::CYCCNT)] +// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +const APP: () = { + #[task(schedule = [b])] + fn a(cx: a::Context) { + // .. + } +}; +``` From 4b61c345eb93a06bf393e0f1f839bce421dc35da Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Wed, 16 Oct 2019 16:36:06 -0500 Subject: [PATCH 2/2] ARMv7-M+ --- book/en/src/migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/en/src/migration.md b/book/en/src/migration.md index 5e2f86575c..dd0092d925 100644 --- a/book/en/src/migration.md +++ b/book/en/src/migration.md @@ -191,7 +191,7 @@ argument of the `#[rtfm::app]` attribute. To continue using the cycle counter the `monotonic = rtfm::cyccnt::CYCCNT` argument to the `#[rtfm::app]` attribute. Also, the `Duration` and `Instant` types and the `U32Ext` trait have been moved -into the `rtfm::cyccnt` module. This module is only available on ARMv7-M +into the `rtfm::cyccnt` module. This module is only available on ARMv7-M+ devices. Change this: