mirror/rtic
1
0
Fork 0
mirror of https://github.com/rtic-rs/rtic.git synced 2024-12-01 16:04:33 +01:00
Code Issues Projects Releases Packages Wiki Activity

Docs: Migration docs

Browse source
This commit is contained in:
Henrik Tjäder 2021-12-18 22:35:16 +01:00
parent 833e22da51
commit 8e68c52721
3 changed files with 53 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
book/en/src/migration.md
View file

@ -1,4 +1,4 @@
# Migration Guides # Migration Guides
This section describes how to migrate between different version of RTIC. This section describes how to migrate between different versions of RTIC.
It also acts as a comparing reference between versions. It also acts as a comparing reference between versions.

76
book/en/src/migration/migration_v4.md
View file

@ -1,19 +1,31 @@
# Migrating from v0.4.x to v0.5.0 # Migrating from v0.4.x to v0.5.0
This section covers how to upgrade an application written against RTIC v0.4.x to This section covers how to upgrade an application written against RTFM v0.4.x to
the version v0.5.0 of the framework. the version v0.5.0 of the framework.
## Project name change RTFM -> RTIC
With release [v0.5.2][rtic0.5.2] the name was change to Real-Time Interrupt-driven Concurrency
All occurrences of `RTFM` needs to change to `RTIC`.
See [migration guide RTFM to RTIC](./migration_rtic.md)
[rtic0.5.2]: https://crates.io/crates/cortex-m-rtic/0.5.2
## `Cargo.toml` ## `Cargo.toml`
First, the version of the `cortex-m-rtic` dependency needs to be updated to Change the version of `cortex-m-rtfm` to
`"0.5.0"`. The `timer-queue` feature needs to be removed. `"0.5.0"`, change `rtfm` to `rtic`.
Remove the `timer-queue` feature.
``` toml ``` toml
[dependencies.cortex-m-rtic] [dependencies.cortex-m-rtfm]
# change this # change this
version = "0.4.3" version = "0.4.3"
# into this # into this
[dependencies.cortex-m-rtic]
version = "0.5.0" version = "0.5.0"
# and remove this Cargo feature # and remove this Cargo feature
@ -23,15 +35,15 @@ features = ["timer-queue"]
## `Context` argument ## `Context` argument
All functions inside the `#[rtic::app]` item need to take as first argument a 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 `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 magically injected into the scope of the function by version v0.4.x of the
framework: `resources`, `spawn`, `schedule` -- these variables will become framework: `resources`, `spawn`, `schedule` -- these variables will become
fields of the `Context` structure. Each function within the `#[rtic::app]` item fields of the `Context` structure. Each function within the `#[rtfm::app]` item
gets a different `Context` type. gets a different `Context` type.
``` rust ``` rust
#[rtic::app(/* .. */)] #[rtfm::app(/* .. */)]
const APP: () = { const APP: () = {
// change this // change this
#[task(resources = [x], spawn = [a], schedule = [b])] #[task(resources = [x], spawn = [a], schedule = [b])]
@ -75,11 +87,11 @@ const APP: () = {
## Resources ## Resources
The syntax used to declare resources has been changed from `static mut` The syntax used to declare resources has changed from `static mut`
variables to a `struct Resources`. variables to a `struct Resources`.
``` rust ``` rust
#[rtic::app(/* .. */)] #[rtfm::app(/* .. */)]
const APP: () = { const APP: () = {
// change this // change this
static mut X: u32 = 0; static mut X: u32 = 0;
@ -101,13 +113,13 @@ const APP: () = {
If your application was accessing the device peripherals in `#[init]` through If your application was accessing the device peripherals in `#[init]` through
the `device` variable then you'll need to add `peripherals = true` to the the `device` variable then you'll need to add `peripherals = true` to the
`#[rtic::app]` attribute to continue to access the device peripherals through `#[rtfm::app]` attribute to continue to access the device peripherals through
the `device` field of the `init::Context` structure. the `device` field of the `init::Context` structure.
Change this: Change this:
``` rust ``` rust
#[rtic::app(/* .. */)] #[rtfm::app(/* .. */)]
const APP: () = { const APP: () = {
#[init] #[init]
fn init() { fn init() {
@ -121,7 +133,7 @@ const APP: () = {
Into this: Into this:
``` rust ``` rust
#[rtic::app(/* .. */, peripherals = true)] #[rtfm::app(/* .. */, peripherals = true)]
// ^^^^^^^^^^^^^^^^^^ // ^^^^^^^^^^^^^^^^^^
const APP: () = { const APP: () = {
#[init] #[init]
@ -137,13 +149,14 @@ const APP: () = {
## `#[interrupt]` and `#[exception]` ## `#[interrupt]` and `#[exception]`
The `#[interrupt]` and `#[exception]` attributes have been removed. To declare Remove the attributes `#[interrupt]` and `#[exception]`.
hardware tasks in v0.5.x use the `#[task]` attribute with the `binds` argument. To declare hardware tasks in v0.5.x use the `#[task]`
attribute with the `binds` argument instead.
Change this: Change this:
``` rust ``` rust
#[rtic::app(/* .. */)] #[rtfm::app(/* .. */)]
const APP: () = { const APP: () = {
// hardware tasks // hardware tasks
#[exception] #[exception]
@ -163,7 +176,7 @@ const APP: () = {
Into this: Into this:
``` rust ``` rust
#[rtic::app(/* .. */)] #[rtfm::app(/* .. */)]
const APP: () = { const APP: () = {
#[task(binds = SVCall)] #[task(binds = SVCall)]
// ^^^^^^^^^^^^^^ // ^^^^^^^^^^^^^^
@ -183,25 +196,26 @@ const APP: () = {
## `schedule` ## `schedule`
The `schedule` API no longer requires the `timer-queue` cargo feature, which has The `schedule` API no longer requires the `timer-queue` cargo feature.
been removed. To use the `schedule` API one must To use the `schedule` API one must first define the monotonic timer the
first define the monotonic timer the runtime will use using the `monotonic` runtime will use using the `monotonic` argument of the `#[rtfm::app]` attribute.
argument of the `#[rtic::app]` attribute. To continue using the cycle counter To continue using the cycle counter (CYCCNT) as the monotonic timer,
(CYCCNT) as the monotonic timer, and match the behavior of version v0.4.x, add and match the behavior of version v0.4.x, add the `monotonic = rtfm::cyccnt::CYCCNT`
the `monotonic = rtic::cyccnt::CYCCNT` argument to the `#[rtic::app]` attribute. argument to the `#[rtfm::app]` attribute.
Also, the `Duration` and `Instant` types and the `U32Ext` trait have been moved Also, the `Duration` and `Instant` types and the `U32Ext` trait moved
into the `rtic::cyccnt` module. This module is only available on ARMv7-M+ into the `rtfm::cyccnt` module.
devices. The removal of the `timer-queue` also brings back the `DWT` peripheral This module is only available on ARMv7-M+ devices.
inside the core peripherals struct, this will need to be enabled by the application The removal of the `timer-queue` also brings back the `DWT` peripheral
inside `init`. inside the core peripherals struct, if `DWT` is required,
ensure it is enabled by the application inside `init`.
Change this: Change this:
``` rust ``` rust
use rtic::{Duration, Instant, U32Ext}; use rtfm::{Duration, Instant, U32Ext};
#[rtic::app(/* .. */)] #[rtfm::app(/* .. */)]
const APP: () = { const APP: () = {
#[task(schedule = [b])] #[task(schedule = [b])]
fn a() { fn a() {
@ -213,10 +227,10 @@ const APP: () = {
Into this: Into this:
``` rust ``` rust
use rtic::cyccnt::{Duration, Instant, U32Ext}; use rtfm::cyccnt::{Duration, Instant, U32Ext};
// ^^^^^^^^ // ^^^^^^^^
#[rtic::app(/* .. */, monotonic = rtic::cyccnt::CYCCNT)] #[rtfm::app(/* .. */, monotonic = rtfm::cyccnt::CYCCNT)]
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
const APP: () = { const APP: () = {
#[init] #[init]

10
book/en/src/migration/migration_v5.md
View file

@ -71,7 +71,7 @@ mod app {
} }
``` ```
## Move Dispatchers from `extern "C"` to app arguments. ## Move Dispatchers from `extern "C"` to app arguments
Change Change
@ -171,7 +171,10 @@ fn b(_: b::Context) {}
## Symmetric locks ## Symmetric locks
Now RTIC utilizes symmetric locks, this means that the `lock` method need 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: Now RTIC utilizes symmetric locks, this means that the `lock` method need
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
#[task(priority = 2, resources = [r])] #[task(priority = 2, resources = [r])]
@ -354,6 +357,7 @@ Note that the attributes `spawn` and `schedule` are no longer needed.
### Extern tasks ### Extern tasks
Both software and hardware tasks can now be defined external to the `mod app`. Previously this was possible only by implementing a trampoline calling out the task implementation. Both software and hardware tasks can now be defined external to the `mod app`.
Previously this was possible only by implementing a trampoline calling out the task implementation.
See examples `examples/extern_binds.rs` and `examples/extern_spawn.rs`. See examples `examples/extern_binds.rs` and `examples/extern_spawn.rs`.