diff options
| -rw-r--r-- | .github/workflows/build.yml | 5 | ||||
| -rw-r--r-- | README.md | 26 | ||||
| -rw-r--r-- | book/en/src/SUMMARY.md | 6 | ||||
| -rw-r--r-- | book/en/src/by-example.md | 8 | ||||
| -rw-r--r-- | book/en/src/by-example/app.md | 13 | ||||
| -rw-r--r-- | book/en/src/by-example/new.md | 18 | ||||
| -rw-r--r-- | book/en/src/by-example/resources.md | 6 | ||||
| -rw-r--r-- | book/en/src/by-example/tips.md | 1 | ||||
| -rw-r--r-- | book/en/src/migration.md | 333 | ||||
| -rw-r--r-- | book/en/src/migration/migration_rtic.md (renamed from book/en/src/migration_rtic.md) | 4 | ||||
| -rw-r--r-- | book/en/src/migration/migration_v4.md | 233 | ||||
| -rw-r--r-- | book/en/src/migration/migration_v5.md | 96 | ||||
| -rw-r--r-- | examples/t-schedule-core-stable.rs | 28 | ||||
| -rw-r--r-- | macros/src/codegen.rs | 2 | ||||
| -rw-r--r-- | macros/src/codegen/module.rs | 4 | ||||
| -rw-r--r-- | macros/src/codegen/pre_init.rs | 4 | ||||
| -rw-r--r-- | macros/src/codegen/spawn_body.rs | 5 | ||||
| -rw-r--r-- | macros/src/codegen/timer_queue.rs | 3 | ||||
| -rw-r--r-- | macros/src/codegen/util.rs | 2 | ||||
| -rw-r--r-- | ui/single/locals-cfg.stderr | 10 | ||||
| -rw-r--r-- | ui/single/resources-cfg.stderr | 4 |
21 files changed, 434 insertions, 377 deletions
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 5a47a757..8da98678 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -608,7 +608,7 @@ jobs: - name: mdBook Action uses: peaceiris/actions-mdbook@v1.1.11 with: - mdbook-version: '0.3.1' + mdbook-version: 'latest' - name: Build book in English run: cd book/en && mdbook build @@ -663,8 +663,7 @@ jobs: - name: mdBook Action uses: peaceiris/actions-mdbook@v1.1.11 with: - mdbook-version: '0.3.1' - # mdbook-version: 'latest' + mdbook-version: 'latest' - name: Remove cargo-config run: rm -f .cargo/config @@ -4,10 +4,12 @@ A concurrency framework for building real-time systems. Formerly known as Real-Time For the Masses. - - - - +[](https://crates.io/crates/cortex-m-rtic) +[](https://docs.rs/cortex-m-rtic) +[](https://rtic.rs/) +[](https://github.com/rust-lang/rust/releases/tag/1.36.0) +[](https://matrix.to/#/#rtic:matrix.org) +[](https://hackmd.io/@xmis9JvZT8Gvo9lOEKyZ4Q/SkBJKsjuH) ## Features @@ -52,23 +54,29 @@ Formerly known as Real-Time For the Masses. ## [User documentation](https://rtic.rs) -## [API reference](https://rtic.rs/0.5/api/) +## [API reference](https://rtic.rs/stable/api/) ## Chat + Join us and talk about RTIC in the [Matrix room][matrix-room]. +Weekly meeting notes can be found over at [HackMD][hackmd] + [matrix-room]: https://matrix.to/#/#rtic:matrix.org +[hackmd]: https://hackmd.io/@xmis9JvZT8Gvo9lOEKyZ4Q/SkBJKsjuH ## Contributing -New features and big changes should go through the RFC process in the [dedicated RFC repository][rfcs]. + +New features and big changes should go through the RFC process in the +[dedicated RFC repository][rfcs]. [rfcs]: https://github.com/rtic-rs/rfcs ## Acknowledgments -This crate is based on [the Real-Time For the Masses language][rtfm-lang] created by the Embedded -Systems group at [Luleå University of Technology][ltu], led by [Prof. Per -Lindgren][per]. +This crate is based on [the Real-Time For the Masses language][rtfm-lang] +created by the Embedded Systems group at [Luleå University of Technology][ltu], +led by [Prof. Per Lindgren][per]. [rtfm-lang]: http://www.rtfm-lang.org/ [ltu]: https://www.ltu.se/?l=en diff --git a/book/en/src/SUMMARY.md b/book/en/src/SUMMARY.md index a573cbb5..e1a4a330 100644 --- a/book/en/src/SUMMARY.md +++ b/book/en/src/SUMMARY.md @@ -10,8 +10,10 @@ - [Types, Send and Sync](./by-example/types-send-sync.md) - [Starting a new project](./by-example/new.md) - [Tips & tricks](./by-example/tips.md) -- [Migrating from v0.4.x to v0.5.0](./migration.md) -- [Migrating from RTFM to RTIC](./migration_rtic.md) +- [Migration Guides](./migration.md) + - [v0.5.x to v0.6.x](./migration/migration_v5.md) + - [v0.4.x to v0.5.x](./migration/migration_v4.md) + - [RTFM to RTIC](./migration/migration_rtic.md) - [Under the hood](./internals.md) - [Interrupt configuration](./internals/interrupt-configuration.md) - [Non-reentrancy](./internals/non-reentrancy.md) diff --git a/book/en/src/by-example.md b/book/en/src/by-example.md index 38985da1..e4441fd9 100644 --- a/book/en/src/by-example.md +++ b/book/en/src/by-example.md @@ -14,3 +14,11 @@ program. Check [the embedded Rust book] for instructions on how to set up an embedded development environment that includes QEMU. [the embedded Rust book]: https://rust-embedded.github.io/book/intro/install.html + +## Real World Examples + +The following are examples of RTFM being used in real world projects. + +### RTFM V0.4.2 + +- [etrombly/sandbox](https://github.com/etrombly/sandbox/tree/41d423bcdd0d8e42fd46b79771400a8ca349af55). A hardware zen garden that draws patterns in sand. Patterns are sent over serial using G-code. diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md index ab6f4524..c4f18c7a 100644 --- a/book/en/src/by-example/app.md +++ b/book/en/src/by-example/app.md @@ -7,11 +7,14 @@ This is the smallest possible RTIC application: ``` All RTIC applications use the [`app`] attribute (`#[app(..)]`). This attribute -must be applied to a `mod`-item. The `app` attribute has -a mandatory `device` argument that takes a *path* as a value. This path must -point to a *peripheral access crate* (PAC) generated using [`svd2rust`] -**v0.14.x** or newer. The `app` attribute will expand into a suitable entry -point so it's not required to use the [`cortex_m_rt::entry`] attribute. +must be applied to a `mod`-item. The `app` attribute has a mandatory `device` +argument that takes a *path* as a value. This must be a full path pointing to a +*peripheral access crate* (PAC) generated using [`svd2rust`] **v0.14.x** or +newer. More details can be found in the [Starting a new project](./new.md) +section. + +The `app` attribute will expand into a suitable entry point so it's not required +to use the [`cortex_m_rt::entry`] attribute. [`app`]: ../../../api/cortex_m_rtic_macros/attr.app.html [`svd2rust`]: https://crates.io/crates/svd2rust diff --git a/book/en/src/by-example/new.md b/book/en/src/by-example/new.md index 866a9fa5..82681bf4 100644 --- a/book/en/src/by-example/new.md +++ b/book/en/src/by-example/new.md @@ -52,7 +52,23 @@ $ curl \ > src/main.rs ``` -That example depends on the `panic-semihosting` crate: +The `init` example uses the `lm3s6965` device. Remember to adjust the `device` +argument in the app macro attribute to match the path of your PAC crate, if +different, and add peripherals or other arguments if needed. Although aliases +can be used, this needs to be a full path (from the crate root). For many +devices, it is common for the HAL implementation crate (aliased as `hal`) or +Board Support crate to re-export the PAC as `pac`, leading to a pattern similar +to the below: + +```rust +use abcd123_hal as hal; +//... + +#[rtic::app(device = crate::hal::pac, peripherals = true, monotonic = rtic::cyccnt::CYCCNT)] +mod app { /*...*/ } +``` + +The `init` example also depends on the `panic-semihosting` crate: ``` console $ cargo add panic-semihosting diff --git a/book/en/src/by-example/resources.md b/book/en/src/by-example/resources.md index d082dfc1..9d90fbe3 100644 --- a/book/en/src/by-example/resources.md +++ b/book/en/src/by-example/resources.md @@ -1,4 +1,4 @@ -## Resources +# Resources The framework provides an abstraction to share data between any of the contexts we saw in the previous section (task handlers, `init` and `idle`): resources. @@ -116,7 +116,9 @@ are required to access the resource even if the resource is contended by several tasks running at different priorities. The downside is that the task only gets a shared reference (`&-`) to the resource, limiting the operations it can perform on it, but where a shared reference is enough this approach reduces the number -of required locks. +of required locks. In addition to simple immutable data, this shared access can +be useful where the resource type safely implements interior mutability, with +appropriate locking or atomic operations of its own. Note that in this release of RTIC it is not possible to request both exclusive access (`&mut-`) and shared access (`&-`) to the *same* resource from different diff --git a/book/en/src/by-example/tips.md b/book/en/src/by-example/tips.md index d8264c90..090b30ad 100644 --- a/book/en/src/by-example/tips.md +++ b/book/en/src/by-example/tips.md @@ -116,6 +116,7 @@ Here's an example where `heapless::Pool` is used to "box" buffers of 128 bytes. ``` rust {{#include ../../../../examples/pool.rs}} ``` + ``` console $ cargo run --example pool {{#include ../../../../ci/expected/pool.run}} diff --git a/book/en/src/migration.md b/book/en/src/migration.md index 7be30943..08feb81e 100644 --- a/book/en/src/migration.md +++ b/book/en/src/migration.md @@ -1,331 +1,4 @@ -# Migration of RTIC +# Migration Guides -## Migrating from v0.5.x to v0.6.0 - -This section describes how to upgrade from v0.5.x to v0.6.0 of the RTIC framework. - -### `Cargo.toml` - version bump - -Change the version of `cortex-m-rtic` to `"0.6.0"`. - -### Module instead of Const - -With the support of attributes on modules the `const APP` workaround is not needed. - -Change - -``` rust -#[rtic::app(/* .. */)] -const APP: () = { - [code here] -}; -``` - -into - -``` rust -#[rtic::app(/* .. */)] -mod app { - [code here] -} -``` - -Now that a regular Rust module is used it means it is possible to have custom -user code within that module. -Additionally, it means that `use`-statements for resources etc may be required. - -### Init always returns late resources - -In order to make the API more symmetric the #[init]-task always returns a late resource. - -From this: - -``` rust -#[rtic::app(device = lm3s6965)] -mod app { - #[init] - fn init(_: init::Context) { - rtic::pend(Interrupt::UART0); - } - [more code] -} -``` - -to this: - -``` rust -#[rtic::app(device = lm3s6965)] -mod app { - #[init] - fn init(_: init::Context) -> init::LateResources { - rtic::pend(Interrupt::UART0); - - init::LateResources {} - } - [more code] -} -``` - -### Resources struct - #[resources] - -Previously the RTIC resources had to be in in a struct named exactly "Resources": - -``` rust -struct Resources { - // Resources defined in here -} -``` - -With RTIC v0.6.0 the resources struct is annotated similarly like -`#[task]`, `#[init]`, `#[idle]`: with an attribute `#[resources]` - -``` rust -#[resources] -struct Resources { - // Resources defined in here -} -``` - -In fact, the name of the struct is now up to the developer: - -``` rust -#[resources] -struct whateveryouwant { - // Resources defined in here -} -``` - -would work equally well. - -## Migrating from v0.4.x to v0.5.0 - -This section covers how to upgrade an application written against RTIC v0.4.x to -the version v0.5.0 of the framework. - -### `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. - -``` toml -[dependencies.cortex-m-rtic] -# change this -version = "0.4.3" - -# into this -version = "0.5.0" - -# and remove this Cargo feature -features = ["timer-queue"] -# ^^^^^^^^^^^^^ -``` - -### `Context` argument - -All functions inside the `#[rtic::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 -gets a different `Context` type. - -``` rust -#[rtic::app(/* .. */)] -const APP: () = { - // change this - #[task(resources = [x], spawn = [a], schedule = [b])] - fn foo() { - resources.x.lock(|x| /* .. */); - spawn.a(message); - schedule.b(baseline); - } - - // into this - #[task(resources = [x], spawn = [a], schedule = [b])] - fn foo(mut cx: foo::Context) { - // ^^^^^^^^^^^^^^^^^^^^ - - cx.resources.x.lock(|x| /* .. */); - // ^^^ - - cx.spawn.a(message); - // ^^^ - - cx.schedule.b(message, baseline); - // ^^^ - } - - // change this - #[init] - fn init() { - // .. - } - - // into this - #[init] - fn init(cx: init::Context) { - // ^^^^^^^^^^^^^^^^^ - // .. - } - - // .. -}; -``` - -### Resources - -The syntax used to declare resources has been changed from `static mut` -variables to a `struct Resources`. - -``` rust -#[rtic::app(/* .. */)] -const APP: () = { - // change this - static mut X: u32 = 0; - static mut Y: u32 = (); // late resource - - // into this - struct Resources { - #[init(0)] // <- initial value - X: u32, // NOTE: we suggest changing the naming style to `snake_case` - - Y: u32, // late resource - } - - // .. -}; -``` - -### Device peripherals - -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 -the `device` field of the `init::Context` structure. - -Change this: - -``` rust -#[rtic::app(/* .. */)] -const APP: () = { - #[init] - fn init() { - device.SOME_PERIPHERAL.write(something); - } - - // .. -}; -``` - -Into this: - -``` rust -#[rtic::app(/* .. */, peripherals = true)] -// ^^^^^^^^^^^^^^^^^^ -const APP: () = { - #[init] - fn init(cx: init::Context) { - // ^^^^^^^^^^^^^^^^^ - cx.device.SOME_PERIPHERAL.write(something); - // ^^^ - } - - // .. -}; -``` - -### `#[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. - -Change this: - -``` rust -#[rtic::app(/* .. */)] -const APP: () = { - // hardware tasks - #[exception] - fn SVCall() { /* .. */ } - - #[interrupt] - fn UART0() { /* .. */ } - - // software task - #[task] - fn foo() { /* .. */ } - - // .. -}; -``` - -Into this: - -``` rust -#[rtic::app(/* .. */)] -const APP: () = { - #[task(binds = SVCall)] - // ^^^^^^^^^^^^^^ - fn svcall(cx: svcall::Context) { /* .. */ } - // ^^^^^^ we suggest you use a `snake_case` name here - - #[task(binds = UART0)] - // ^^^^^^^^^^^^^ - fn uart0(cx: uart0::Context) { /* .. */ } - - #[task] - fn foo(cx: foo::Context) { /* .. */ } - - // .. -}; -``` - -### `schedule` - -The `timer-queue` feature 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. - -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`. - -Change this: - -``` rust -use rtic::{Duration, Instant, U32Ext}; - -#[rtic::app(/* .. */)] -const APP: () = { - #[task(schedule = [b])] - fn a() { - // .. - } -}; -``` - -Into this: - -``` rust -use rtic::cyccnt::{Duration, Instant, U32Ext}; -// ^^^^^^^^ - -#[rtic::app(/* .. */, monotonic = rtic::cyccnt::CYCCNT)] -// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -const APP: () = { - #[init] - fn init(cx: init::Context) { - cx.core.DWT.enable_cycle_counter(); - // optional, configure the DWT run without a debugger connected - cx.core.DCB.enable_trace(); - } - #[task(schedule = [b])] - fn a(cx: a::Context) { - // .. - } -}; -``` +This section describes how to migrate between different version of RTIC. +It also acts as a comparing reference between versions. diff --git a/book/en/src/migration_rtic.md b/book/en/src/migration/migration_rtic.md index 555f1bb7..c027da35 100644 --- a/book/en/src/migration_rtic.md +++ b/book/en/src/migration/migration_rtic.md @@ -8,14 +8,11 @@ change. [RFC #33]: https://github.com/rtic-rs/rfcs/pull/33 - - ## `Cargo.toml` First, the `cortex-m-rtfm` dependency needs to be updated to `cortex-m-rtic`. - ``` toml [dependencies] # change this @@ -51,4 +48,3 @@ const APP: () = { }; ``` - diff --git a/book/en/src/migration/migration_v4.md b/book/en/src/migration/migration_v4.md new file mode 100644 index 00000000..ac59d8c9 --- /dev/null +++ b/book/en/src/migration/migration_v4.md @@ -0,0 +1,233 @@ +# Migrating from v0.4.x to v0.5.0 + +This section covers how to upgrade an application written against RTIC v0.4.x to +the version v0.5.0 of the framework. + +## `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. + +``` toml +[dependencies.cortex-m-rtic] +# change this +version = "0.4.3" + +# into this +version = "0.5.0" + +# and remove this Cargo feature +features = ["timer-queue"] +# ^^^^^^^^^^^^^ +``` + +## `Context` argument + +All functions inside the `#[rtic::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 +gets a different `Context` type. + +``` rust +#[rtic::app(/* .. */)] +const APP: () = { + // change this + #[task(resources = [x], spawn = [a], schedule = [b])] + fn foo() { + resources.x.lock(|x| /* .. */); + spawn.a(message); + schedule.b(baseline); + } + + // into this + #[task(resources = [x], spawn = [a], schedule = [b])] + fn foo(mut cx: foo::Context) { + // ^^^^^^^^^^^^^^^^^^^^ + + cx.resources.x.lock(|x| /* .. */); + // ^^^ + + cx.spawn.a(message); + // ^^^ + + cx.schedule.b(message, baseline); + // ^^^ + } + + // change this + #[init] + fn init() { + // .. + } + + // into this + #[init] + fn init(cx: init::Context) { + // ^^^^^^^^^^^^^^^^^ + // .. + } + + // .. +}; +``` + +## Resources + +The syntax used to declare resources has been changed from `static mut` +variables to a `struct Resources`. + +``` rust +#[rtic::app(/* .. */)] +const APP: () = { + // change this + static mut X: u32 = 0; + static mut Y: u32 = (); // late resource + + // into this + struct Resources { + #[init(0)] // <- initial value + X: u32, // NOTE: we suggest changing the naming style to `snake_case` + + Y: u32, // late resource + } + + // .. +}; +``` + +## Device peripherals + +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 +the `device` field of the `init::Context` structure. + +Change this: + +``` rust +#[rtic::app(/* .. */)] +const APP: () = { + #[init] + fn init() { + device.SOME_PERIPHERAL.write(something); + } + + // .. +}; +``` + +Into this: + +``` rust +#[rtic::app(/* .. */, peripherals = true)] +// ^^^^^^^^^^^^^^^^^^ +const APP: () = { + #[init] + fn init(cx: init::Context) { + // ^^^^^^^^^^^^^^^^^ + cx.device.SOME_PERIPHERAL.write(something); + // ^^^ + } + + // .. +}; +``` + +## `#[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. + +Change this: + +``` rust +#[rtic::app(/* .. */)] +const APP: () = { + // hardware tasks + #[exception] + fn SVCall() { /* .. */ } + + #[interrupt] + fn UART0() { /* .. */ } + + // software task + #[task] + fn foo() { /* .. */ } + + // .. +}; +``` + +Into this: + +``` rust +#[rtic::app(/* .. */)] +const APP: () = { + #[task(binds = SVCall)] + // ^^^^^^^^^^^^^^ + fn svcall(cx: svcall::Context) { /* .. */ } + // ^^^^^^ we suggest you use a `snake_case` name here + + #[task(binds = UART0)] + // ^^^^^^^^^^^^^ + fn uart0(cx: uart0::Context) { /* .. */ } + + #[task] + fn foo(cx: foo::Context) { /* .. */ } + + // .. +}; +``` + +## `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. + +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`. + +Change this: + +``` rust +use rtic::{Duration, Instant, U32Ext}; + +#[rtic::app(/* .. */)] +const APP: () = { + #[task(schedule = [b])] + fn a() { + // .. + } +}; +``` + +Into this: + +``` rust +use rtic::cyccnt::{Duration, Instant, U32Ext}; +// ^^^^^^^^ + +#[rtic::app(/* .. */, monotonic = rtic::cyccnt::CYCCNT)] +// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +const APP: () = { + #[init] + fn init(cx: init::Context) { + cx.core.DWT.enable_cycle_counter(); + // optional, configure the DWT run without a debugger connected + cx.core.DCB.enable_trace(); + } + #[task(schedule = [b])] + fn a(cx: a::Context) { + // .. + } +}; +``` diff --git a/book/en/src/migration/migration_v5.md b/book/en/src/migration/migration_v5.md new file mode 100644 index 00000000..1d83444e --- /dev/null +++ b/book/en/src/migration/migration_v5.md @@ -0,0 +1,96 @@ +# Migrating from v0.5.x to v0.6.0 + +This section describes how to upgrade from v0.5.x to v0.6.0 of the RTIC framework. + +## `Cargo.toml` - version bump + +Change the version of `cortex-m-rtic` to `"0.6.0"`. + +## Module instead of Const + +With the support of attributes on modules the `const APP` workaround is not needed. + +Change + +``` rust +#[rtic::app(/* .. */)] +const APP: () = { + [code here] +}; +``` + +into + +``` rust +#[rtic::app(/* .. */)] +mod app { + [code here] +} +``` + +Now that a regular Rust module is used it means it is possible to have custom +user code within that module. +Additionally, it means that `use`-statements for resources etc may be required. + +## Init always returns late resources + +In order to make the API more symmetric the #[init]-task always returns a late resource. + +From this: + +``` rust +#[rtic::app(device = lm3s6965)] +mod app { + #[init] + fn init(_: init::Context) { + rtic::pend(Interrupt::UART0); + } + [more code] +} +``` + +to this: + +``` rust +#[rtic::app(device = lm3s6965)] +mod app { + #[init] + fn init(_: init::Context) -> init::LateResources { + rtic::pend(Interrupt::UART0); + + init::LateResources {} + } + [more code] +} +``` + +## Resources struct - #[resources] + +Previously the RTIC resources had to be in in a struct named exactly "Resources": + +``` rust +struct Resources { + // Resources defined in here +} +``` + +With RTIC v0.6.0 the resources struct is annotated similarly like +`#[task]`, `#[init]`, `#[idle]`: with an attribute `#[resources]` + +``` rust +#[resources] +struct Resources { + // Resources defined in here +} +``` + +In fact, the name of the struct is now up to the developer: + +``` rust +#[resources] +struct whateveryouwant { + // Resources defined in here +} +``` + +would work equally well. diff --git a/examples/t-schedule-core-stable.rs b/examples/t-schedule-core-stable.rs new file mode 100644 index 00000000..c2a8fdb5 --- /dev/null +++ b/examples/t-schedule-core-stable.rs @@ -0,0 +1,28 @@ +//! [compile-pass] Check `schedule` code generation + +#![deny(unsafe_code)] +#![deny(warnings)] +#![no_main] +#![no_std] + +use panic_halt as _; + +#[rtic::app(device = lm3s6965, monotonic = rtic::cyccnt::CYCCNT)] +mod app { + #[init] + fn init(c: init::Context) -> init::LateResources { + let _c: rtic::Peripherals = c.core; + + init::LateResources {} + } + + #[task] + fn some_task(_: some_task::Context) {} + + // RTIC requires that unused interrupts are declared in an extern block when + // using software tasks; these free interrupts will be used to dispatch the + // software tasks. + extern "C" { + fn SSI0(); + } +} diff --git a/macros/src/codegen.rs b/macros/src/codegen.rs index a44266ad..a256ac75 100644 --- a/macros/src/codegen.rs +++ b/macros/src/codegen.rs @@ -161,7 +161,7 @@ pub fn app(app: &App, analysis: &Analysis, extra: &Extra) -> TokenStream2 { /// Implementation details mod #name { /// Always include the device crate which contains the vector table - use #device as _; + use #device as you_must_enable_the_rt_feature_for_the_pac_in_your_cargo_toml; #(#imports)* #(#user_imports)* diff --git a/macros/src/codegen/module.rs b/macros/src/codegen/module.rs index 2e51e7db..3d90cbd3 100644 --- a/macros/src/codegen/module.rs +++ b/macros/src/codegen/module.rs @@ -15,7 +15,7 @@ pub fn codegen(ctxt: Context, resources_tick: bool, app: &App, extra: &Extra) -> let mut lt = None; match ctxt { Context::Init => { - if app.uses_schedule() { + if extra.monotonic.is_some() { let m = extra.monotonic(); fields.push(quote!( @@ -277,7 +277,7 @@ pub fn codegen(ctxt: Context, resources_tick: bool, app: &App, extra: &Extra) -> }; let core = if ctxt.is_init() { - if app.uses_schedule() { + if extra.monotonic.is_some() { Some(quote!(core: rtic::Peripherals,)) } else { Some(quote!(core: rtic::export::Peripherals,)) diff --git a/macros/src/codegen/pre_init.rs b/macros/src/codegen/pre_init.rs index 9c5f35ec..2aaf9ebd 100644 --- a/macros/src/codegen/pre_init.rs +++ b/macros/src/codegen/pre_init.rs @@ -53,14 +53,14 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec<TokenStream let interrupt = util::interrupt_ident(); stmts.push(quote!( core.NVIC.set_priority( - #device::#interrupt::#name, + you_must_enable_the_rt_feature_for_the_pac_in_your_cargo_toml::#interrupt::#name, rtic::export::logical2hw(#priority, #nvic_prio_bits), ); )); // NOTE unmask the interrupt *after* setting its priority: changing the priority of a pended // interrupt is implementation defined - stmts.push(quote!(rtic::export::NVIC::unmask(#device::#interrupt::#name);)); + stmts.push(quote!(rtic::export::NVIC::unmask(you_must_enable_the_rt_feature_for_the_pac_in_your_cargo_toml::#interrupt::#name);)); } // Set exception priorities diff --git a/macros/src/codegen/spawn_body.rs b/macros/src/codegen/spawn_body.rs index 4ecd0757..f29393a6 100644 --- a/macros/src/codegen/spawn_body.rs +++ b/macros/src/codegen/spawn_body.rs @@ -10,7 +10,7 @@ pub fn codegen( name: &Ident, app: &App, analysis: &Analysis, - extra: &Extra, + _extra: &Extra, ) -> TokenStream2 { let spawnee = &app.software_tasks[name]; let priority = spawnee.args.priority; @@ -42,12 +42,11 @@ pub fn codegen( ) }; - let device = extra.device; let enum_ = util::interrupt_ident(); let interrupt = &analysis.interrupts.get(&priority); let pend = { quote!( - rtic::pend(#device::#enum_::#interrupt); + rtic::pend(you_must_enable_the_rt_feature_for_the_pac_in_your_cargo_toml::#enum_::#interrupt); ) }; diff --git a/macros/src/codegen/timer_queue.rs b/macros/src/codegen/timer_queue.rs index 030158e2..0abbf49d 100644 --- a/macros/src/codegen/timer_queue.rs +++ b/macros/src/codegen/timer_queue.rs @@ -72,7 +72,6 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec<TokenStream // Timer queue handler { - let device = extra.device; let arms = timer_queue .tasks .iter() @@ -88,7 +87,7 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec<TokenStream let pend = { quote!( - rtic::pend(#device::#enum_::#interrupt); + rtic::pend(you_must_enable_the_rt_feature_for_the_pac_in_your_cargo_toml::#enum_::#interrupt); ) }; diff --git a/macros/src/codegen/util.rs b/macros/src/codegen/util.rs index 2f9f3cce..41ee3ca7 100644 --- a/macros/src/codegen/util.rs +++ b/macros/src/codegen/util.rs @@ -83,7 +83,7 @@ pub fn instants_ident(task: &Ident) -> Ident { pub fn interrupt_ident() -> Ident { let span = Span::call_site(); - Ident::new("Interrupt", span) + Ident::new("interrupt", span) } /// Whether `name` is an exception with configurable priority diff --git a/ui/single/locals-cfg.stderr b/ui/single/locals-cfg.stderr index e58bd935..0af1293f 100644 --- a/ui/single/locals-cfg.stderr +++ b/ui/single/locals-cfg.stderr @@ -31,11 +31,5 @@ error[E0425]: cannot find value `FOO` in this scope error: duplicate lang item in crate `panic_halt` (which `$CRATE` depends on): `panic_impl`. | = note: the lang item is first defined in crate `std` (which `$CRATE` depends on) - = note: first definition in `std` loaded from /usr/share/rust/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib/libstd-cf0f33af3a901778.rlib - = note: second definition in `panic_halt` loaded from $DIR/target/tests/target/x86_64-unknown-linux-gnu/debug/deps/libpanic_halt-ba6f0ab3439cbc7e.rmeta - -error: duplicate lang item in crate `panic_semihosting`: `panic_impl`. - | - = note: the lang item is first defined in crate `panic_halt` (which `$CRATE` depends on) - = note: first definition in `panic_halt` loaded from $DIR/target/tests/target/x86_64-unknown-linux-gnu/debug/deps/libpanic_halt-ba6f0ab3439cbc7e.rmeta - = note: second definition in `panic_semihosting` loaded from $DIR/target/tests/target/x86_64-unknown-linux-gnu/debug/deps/libpanic_semihosting-805015f4a2d05965.rmeta + = note: first definition in `std` loaded from /usr/share/rust/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib/libstd-f14aca24435a5414.rlib + = note: second definition in `panic_halt` loaded from $DIR/target/tests/target/x86_64-unknown-linux-gnu/debug/deps/libpanic_halt-33949299fdfa2375.rmeta diff --git a/ui/single/resources-cfg.stderr b/ui/single/resources-cfg.stderr index 17f08d81..0b0c749d 100644 --- a/ui/single/resources-cfg.stderr +++ b/ui/single/resources-cfg.stderr @@ -1,8 +1,8 @@ error: duplicate lang item in crate `panic_halt` (which `$CRATE` depends on): `panic_impl`. | = note: the lang item is first defined in crate `std` (which `$CRATE` depends on) - = note: first definition in `std` loaded from /usr/share/rust/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib/libstd-cf0f33af3a901778.rlib - = note: second definition in `panic_halt` loaded from $DIR/target/tests/target/x86_64-unknown-linux-gnu/debug/deps/libpanic_halt-ba6f0ab3439cbc7e.rmeta + = note: first definition in `std` loaded from /usr/share/rust/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib/libstd-f14aca24435a5414.rlib + = note: second definition in `panic_halt` loaded from $DIR/target/tests/target/x86_64-unknown-linux-gnu/debug/deps/libpanic_halt-33949299fdfa2375.rmeta error[E0609]: no field `o1` on type `initResources<'_>` --> $DIR/resources-cfg.rs:47:21 |