diff options
Diffstat (limited to 'book/en/src/migration/migration_v2')
| -rw-r--r-- | book/en/src/migration/migration_v2/async_tasks.md | 55 | ||||
| -rw-r--r-- | book/en/src/migration/migration_v2/complete_example.md | 169 | ||||
| -rw-r--r-- | book/en/src/migration/migration_v2/monotonics.md | 13 | ||||
| -rw-r--r-- | book/en/src/migration/migration_v2/nightly.md | 5 | ||||
| -rw-r--r-- | book/en/src/migration/migration_v2/rtic-sync.md | 9 |
5 files changed, 0 insertions, 251 deletions
diff --git a/book/en/src/migration/migration_v2/async_tasks.md b/book/en/src/migration/migration_v2/async_tasks.md deleted file mode 100644 index 54e0893..0000000 --- a/book/en/src/migration/migration_v2/async_tasks.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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/migration_v2/complete_example.md b/book/en/src/migration/migration_v2/complete_example.md deleted file mode 100644 index b68f1ef..0000000 --- a/book/en/src/migration/migration_v2/complete_example.md +++ /dev/null @@ -1,169 +0,0 @@ -# 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<Output<PushPull>>, - 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::<u64, 1, 1000>::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::<u64, 1, 1000>::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::<u64, 1, 1000>::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::<u64, 1, 1000>::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/migration_v2/monotonics.md b/book/en/src/migration/migration_v2/monotonics.md deleted file mode 100644 index a8b0dba..0000000 --- a/book/en/src/migration/migration_v2/monotonics.md +++ /dev/null @@ -1,13 +0,0 @@ -# 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/migration_v2/nightly.md b/book/en/src/migration/migration_v2/nightly.md deleted file mode 100644 index 09f6e33..0000000 --- a/book/en/src/migration/migration_v2/nightly.md +++ /dev/null @@ -1,5 +0,0 @@ -# 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/migration_v2/rtic-sync.md b/book/en/src/migration/migration_v2/rtic-sync.md deleted file mode 100644 index fefde03..0000000 --- a/book/en/src/migration/migration_v2/rtic-sync.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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 |