mirror of
https://github.com/rtic-rs/rtic.git
synced 2024-11-29 06:54:33 +01:00
Docs: Migration docs
This commit is contained in:
parent
833e22da51
commit
8e68c52721
3 changed files with 53 additions and 35 deletions
|
@ -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.
|
||||||
|
|
|
@ -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]
|
||||||
|
|
|
@ -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`.
|
||||||
|
|
Loading…
Reference in a new issue