mirror/rtic
1
0
Fork 0
mirror of https://github.com/rtic-rs/rtic.git synced 2024-11-29 06:54: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
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.

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

@ -1,19 +1,31 @@
# 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.
## 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`
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.
Change the version of `cortex-m-rtfm` to
`"0.5.0"`, change `rtfm` to `rtic`.
Remove the `timer-queue` feature.
``` toml
[dependencies.cortex-m-rtic]
[dependencies.cortex-m-rtfm]
# change this
version = "0.4.3"
# into this
[dependencies.cortex-m-rtic]
version = "0.5.0"
# and remove this Cargo feature
@ -23,15 +35,15 @@ features = ["timer-queue"]
## `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
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
fields of the `Context` structure. Each function within the `#[rtfm::app]` item
gets a different `Context` type.
``` rust
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
// change this
#[task(resources = [x], spawn = [a], schedule = [b])]
@ -75,11 +87,11 @@ const APP: () = {
## 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`.
``` rust
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
// change this
static mut X: u32 = 0;
@ -101,13 +113,13 @@ const APP: () = {
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
`#[rtfm::app]` attribute to continue to access the device peripherals through
the `device` field of the `init::Context` structure.
Change this:
``` rust
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
#[init]
fn init() {
@ -121,7 +133,7 @@ const APP: () = {
Into this:
``` rust
#[rtic::app(/* .. */, peripherals = true)]
#[rtfm::app(/* .. */, peripherals = true)]
// ^^^^^^^^^^^^^^^^^^
const APP: () = {
#[init]
@ -137,13 +149,14 @@ const APP: () = {
## `#[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.
Remove the attributes `#[interrupt]` and `#[exception]`.
To declare hardware tasks in v0.5.x use the `#[task]`
attribute with the `binds` argument instead.
Change this:
``` rust
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
// hardware tasks
#[exception]
@ -163,7 +176,7 @@ const APP: () = {
Into this:
``` rust
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
#[task(binds = SVCall)]
// ^^^^^^^^^^^^^^
@ -183,25 +196,26 @@ const APP: () = {
## `schedule`
The `schedule` API no longer requires the `timer-queue` cargo feature, which 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.
The `schedule` API no longer requires the `timer-queue` cargo feature.
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 `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`.
Also, the `Duration` and `Instant` types and the `U32Ext` trait moved
into the `rtfm::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, if `DWT` is required,
ensure it is enabled by the application inside `init`.
Change this:
``` rust
use rtic::{Duration, Instant, U32Ext};
use rtfm::{Duration, Instant, U32Ext};
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
#[task(schedule = [b])]
fn a() {
@ -213,10 +227,10 @@ const APP: () = {
Into this:
``` 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: () = {
#[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
@ -171,7 +171,10 @@ fn b(_: b::Context) {}
## 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
#[task(priority = 2, resources = [r])]
@ -354,6 +357,7 @@ Note that the attributes `spawn` and `schedule` are no longer needed.
### 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`.