From 3d97c9e431d7fcb20b1b30bc15c34ccffee03c79 Mon Sep 17 00:00:00 2001 From: datdenkikniet Date: Sat, 22 Apr 2023 21:27:26 +0200 Subject: Move deprecated migration guides to deprecated folder --- book/en/src/migration_v1_v2/async_tasks.md | 55 ++++++++ book/en/src/migration_v1_v2/complete_example.md | 169 ++++++++++++++++++++++++ book/en/src/migration_v1_v2/monotonics.md | 13 ++ book/en/src/migration_v1_v2/nightly.md | 5 + book/en/src/migration_v1_v2/rtic-sync.md | 9 ++ 5 files changed, 251 insertions(+) create mode 100644 book/en/src/migration_v1_v2/async_tasks.md create mode 100644 book/en/src/migration_v1_v2/complete_example.md create mode 100644 book/en/src/migration_v1_v2/monotonics.md create mode 100644 book/en/src/migration_v1_v2/nightly.md create mode 100644 book/en/src/migration_v1_v2/rtic-sync.md (limited to 'book/en/src/migration_v1_v2') diff --git a/book/en/src/migration_v1_v2/async_tasks.md b/book/en/src/migration_v1_v2/async_tasks.md new file mode 100644 index 0000000..54e0893 --- /dev/null +++ b/book/en/src/migration_v1_v2/async_tasks.md @@ -0,0 +1,55 @@ +# Using `async` softare tasks. + +There have been a few changes to software tasks. They are outlined below. + +### Software tasks must now be `async`. + +All software tasks are now required to be `async`. + +#### Required changes. + +All of the tasks in your project that do not bind to an interrupt must now be an `async fn`. For example: + +``` rust +#[task( + local = [ some_resource ], + shared = [ my_shared_resource ], + priority = 2 +)] +fn my_task(cx: my_task::Context) { + cx.local.some_resource.do_trick(); + cx.shared.my_shared_resource.lock(|s| s.do_shared_thing()); +} +``` + +becomes + +``` rust +#[task( + local = [ some_resource ], + shared = [ my_shared_resource ], + priority = 2 +)] +async fn my_task(cx: my_task::Context) { + cx.local.some_resource.do_trick(); + cx.shared.my_shared_resource.lock(|s| s.do_shared_thing()); +} +``` + +## Software tasks may now run forever + +The new `async` software tasks are allowed to run forever, on one precondition: **there must be an `await` within the infinite loop of the task**. An example of such a task: + +``` rust +#[task(local = [ my_channel ] )] +async fn my_task_that_runs_forever(cx: my_task_that_runs_forever::Context) { + loop { + let value = cx.local.my_channel.recv().await; + do_something_with_value(value); + } +} +``` + +## `spawn_after` and `spawn_at` have been removed. + +As discussed in the [Migrating to `rtic-monotonics`](./monotonics.md) chapter, `spawn_after` and `spawn_at` are no longer available. \ No newline at end of file diff --git a/book/en/src/migration_v1_v2/complete_example.md b/book/en/src/migration_v1_v2/complete_example.md new file mode 100644 index 0000000..dc29b25 --- /dev/null +++ b/book/en/src/migration_v1_v2/complete_example.md @@ -0,0 +1,169 @@ +# A complete example of migration + +Below you can find the code for the implementation of the `stm32f3_blinky` example for v1.0.x and for v2.0.0. Further down, a diff is displayed. + +# v1.0.X + +```rust +#![deny(unsafe_code)] +#![deny(warnings)] +#![no_main] +#![no_std] + +use panic_rtt_target as _; +use rtic::app; +use rtt_target::{rprintln, rtt_init_print}; +use stm32f3xx_hal::gpio::{Output, PushPull, PA5}; +use stm32f3xx_hal::prelude::*; +use systick_monotonic::{fugit::Duration, Systick}; + +#[app(device = stm32f3xx_hal::pac, peripherals = true, dispatchers = [SPI1])] +mod app { + use super::*; + + #[shared] + struct Shared {} + + #[local] + struct Local { + led: PA5>, + state: bool, + } + + #[monotonic(binds = SysTick, default = true)] + type MonoTimer = Systick<1000>; + + #[init] + fn init(cx: init::Context) -> (Shared, Local, init::Monotonics) { + // Setup clocks + let mut flash = cx.device.FLASH.constrain(); + let mut rcc = cx.device.RCC.constrain(); + + let mono = Systick::new(cx.core.SYST, 36_000_000); + + rtt_init_print!(); + rprintln!("init"); + + let _clocks = rcc + .cfgr + .use_hse(8.MHz()) + .sysclk(36.MHz()) + .pclk1(36.MHz()) + .freeze(&mut flash.acr); + + // Setup LED + let mut gpioa = cx.device.GPIOA.split(&mut rcc.ahb); + let mut led = gpioa + .pa5 + .into_push_pull_output(&mut gpioa.moder, &mut gpioa.otyper); + led.set_high().unwrap(); + + // Schedule the blinking task + blink::spawn_after(Duration::::from_ticks(1000)).unwrap(); + + ( + Shared {}, + Local { led, state: false }, + init::Monotonics(mono), + ) + } + + #[task(local = [led, state])] + fn blink(cx: blink::Context) { + rprintln!("blink"); + if *cx.local.state { + cx.local.led.set_high().unwrap(); + *cx.local.state = false; + } else { + cx.local.led.set_low().unwrap(); + *cx.local.state = true; + } + blink::spawn_after(Duration::::from_ticks(1000)).unwrap(); + } +} + +``` + +# V2.0.0 + +``` rust +{{ #include ../../../../examples/stm32f3_blinky/src/main.rs }} +``` + +## A diff between the two projects + +_Note_: This diff may not be 100% accurate, but it displays the important changes. + +``` diff +#![no_main] + #![no_std] ++#![feature(type_alias_impl_trait)] + + use panic_rtt_target as _; + use rtic::app; + use stm32f3xx_hal::gpio::{Output, PushPull, PA5}; + use stm32f3xx_hal::prelude::*; +-use systick_monotonic::{fugit::Duration, Systick}; ++use rtic_monotonics::Systick; + + #[app(device = stm32f3xx_hal::pac, peripherals = true, dispatchers = [SPI1])] + mod app { +@@ -20,16 +21,14 @@ mod app { + state: bool, + } + +- #[monotonic(binds = SysTick, default = true)] +- type MonoTimer = Systick<1000>; +- + #[init] + fn init(cx: init::Context) -> (Shared, Local, init::Monotonics) { + // Setup clocks + let mut flash = cx.device.FLASH.constrain(); + let mut rcc = cx.device.RCC.constrain(); + +- let mono = Systick::new(cx.core.SYST, 36_000_000); ++ let mono_token = rtic_monotonics::create_systick_token!(); ++ let mono = Systick::new(cx.core.SYST, 36_000_000, mono_token); + + let _clocks = rcc + .cfgr +@@ -46,7 +45,7 @@ mod app { + led.set_high().unwrap(); + + // Schedule the blinking task +- blink::spawn_after(Duration::::from_ticks(1000)).unwrap(); ++ blink::spawn().unwrap(); + + ( + Shared {}, +@@ -56,14 +55,18 @@ mod app { + } + + #[task(local = [led, state])] +- fn blink(cx: blink::Context) { +- rprintln!("blink"); +- if *cx.local.state { +- cx.local.led.set_high().unwrap(); +- *cx.local.state = false; +- } else { +- cx.local.led.set_low().unwrap(); +- *cx.local.state = true; +- blink::spawn_after(Duration::::from_ticks(1000)).unwrap(); +- } ++ async fn blink(cx: blink::Context) { ++ loop { ++ // A task is now allowed to run forever, provided that ++ // there is an `await` somewhere in the loop. ++ SysTick::delay(1000.millis()).await; ++ rprintln!("blink"); ++ if *cx.local.state { ++ cx.local.led.set_high().unwrap(); ++ *cx.local.state = false; ++ } else { ++ cx.local.led.set_low().unwrap(); ++ *cx.local.state = true; ++ } ++ } ++ } + } +``` \ No newline at end of file diff --git a/book/en/src/migration_v1_v2/monotonics.md b/book/en/src/migration_v1_v2/monotonics.md new file mode 100644 index 0000000..a8b0dba --- /dev/null +++ b/book/en/src/migration_v1_v2/monotonics.md @@ -0,0 +1,13 @@ +# Migrating to `rtic-monotonics` + +In previous versions of `rtic`, monotonics were an integral, tightly coupled part of the `#[rtic::app]`. In this new version, [`rtic-monotonics`] provides them in a more decoupled way. + +The `#[monotonic]` attribute is no longer used. Instead, you use a `create_X_token` from [`rtic-monotonics`]. An invocation of this macro returns an interrupt registration token, which can be used to construct an instance of your desired monotonic. + +`spawn_after` and `spawn_at` are no longer available. Instead, you use the async functions `delay` and `delay_until` provided by ipmlementations of the `rtic_time::Monotonic` trait, available through [`rtic-monotonics`]. + +Check out the [code example](./complete_example.md) for an overview of the required changes. + +For more information on current monotonic implementations, see [the `rtic-monotonics` documentation](https://docs.rs/rtic-monotonics), and [the examples](https://github.com/rtic-rs/rtic/tree/master/examples). + +[`rtic-monotonics`]: ghttps://github.com/rtic/rtic-monotonics \ No newline at end of file diff --git a/book/en/src/migration_v1_v2/nightly.md b/book/en/src/migration_v1_v2/nightly.md new file mode 100644 index 0000000..09f6e33 --- /dev/null +++ b/book/en/src/migration_v1_v2/nightly.md @@ -0,0 +1,5 @@ +# RTIC now requires Rust Nightly + +The new `async` features require that you use a nightly compiler, and that the feature `type_alias_impl_trait` is enabled for your applications. + +To enable this feature, you must add the line `#![type_alias_impl_trait]` to the root file of your project, on the lines below or above where `#![no_std]` and `#![no_main]` are defined. \ No newline at end of file diff --git a/book/en/src/migration_v1_v2/rtic-sync.md b/book/en/src/migration_v1_v2/rtic-sync.md new file mode 100644 index 0000000..fefde03 --- /dev/null +++ b/book/en/src/migration_v1_v2/rtic-sync.md @@ -0,0 +1,9 @@ +# Using `rtic-sync` + +`rtic-sync` provides primitives that can be used for message passing and resource sharing in async context. + +The important structs are: +* The `Arbiter`, which allows you to await access to a shared resource in async contexts without using `lock`. +* `Channel`, which allows you to communicate between tasks (both `async` and non-`async`). + +For more information on these structs, see the [`rtic-sync` docs](https://docs.rs/rtic-sync) \ No newline at end of file -- cgit v1.2.3