From 91c2d4850e31da1bbd49fc668ae79533e7ac3ab4 Mon Sep 17 00:00:00 2001 From: Daniel Carosone Date: Fri, 2 Oct 2020 19:56:17 +1000 Subject: [PATCH 1/3] Shared access is useful with interior mutability --- book/en/src/by-example/resources.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/en/src/by-example/resources.md b/book/en/src/by-example/resources.md index d67a72ff48..9831e55b3b 100644 --- a/book/en/src/by-example/resources.md +++ b/book/en/src/by-example/resources.md @@ -114,7 +114,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 From 3d6a0ea64fb2661ee1150a84425f50c18c2de9ad Mon Sep 17 00:00:00 2001 From: Daniel Carosone Date: Fri, 2 Oct 2020 20:43:52 +1000 Subject: [PATCH 2/3] minor markdownlints --- book/en/src/by-example/resources.md | 2 +- book/en/src/by-example/tips.md | 1 + book/en/src/migration.md | 3 +-- book/en/src/migration_rtic.md | 4 ---- 4 files changed, 3 insertions(+), 7 deletions(-) diff --git a/book/en/src/by-example/resources.md b/book/en/src/by-example/resources.md index 9831e55b3b..9b6e5a809f 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. diff --git a/book/en/src/by-example/tips.md b/book/en/src/by-example/tips.md index 5a44708865..98c1abbf1e 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 6cca64dba4..d382db1724 100644 --- a/book/en/src/migration.md +++ b/book/en/src/migration.md @@ -8,7 +8,6 @@ the version v0.5.0 of the framework. 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 @@ -194,7 +193,7 @@ 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`. +inside `init`. Change this: diff --git a/book/en/src/migration_rtic.md b/book/en/src/migration_rtic.md index 555f1bb710..c027da35fd 100644 --- a/book/en/src/migration_rtic.md +++ b/book/en/src/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: () = { }; ``` - From 987332b831761a681ec5cdda192ead524438df77 Mon Sep 17 00:00:00 2001 From: Daniel Carosone Date: Wed, 7 Oct 2020 09:31:30 +1100 Subject: [PATCH 3/3] minor md lints and wording clarification --- book/en/src/migration/migration_v4.md | 15 ++++++++------- book/en/src/migration/migration_v5.md | 8 ++++---- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/book/en/src/migration/migration_v4.md b/book/en/src/migration/migration_v4.md index 2c4e3ade6f..ac59d8c9fb 100644 --- a/book/en/src/migration/migration_v4.md +++ b/book/en/src/migration/migration_v4.md @@ -3,7 +3,7 @@ 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` +## `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. @@ -21,7 +21,7 @@ features = ["timer-queue"] # ^^^^^^^^^^^^^ ``` -### `Context` argument +## `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 @@ -73,7 +73,7 @@ const APP: () = { }; ``` -### Resources +## Resources The syntax used to declare resources has been changed from `static mut` variables to a `struct Resources`. @@ -97,7 +97,7 @@ const APP: () = { }; ``` -### Device peripherals +## 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 @@ -135,7 +135,7 @@ const APP: () = { }; ``` -### `#[interrupt]` and `#[exception]` +## `#[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. @@ -181,9 +181,10 @@ const APP: () = { }; ``` -### `schedule` +## `schedule` -The `timer-queue` feature has been removed. To use the `schedule` API one must +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 diff --git a/book/en/src/migration/migration_v5.md b/book/en/src/migration/migration_v5.md index 749ddecdba..1d83444e09 100644 --- a/book/en/src/migration/migration_v5.md +++ b/book/en/src/migration/migration_v5.md @@ -2,11 +2,11 @@ This section describes how to upgrade from v0.5.x to v0.6.0 of the RTIC framework. -### `Cargo.toml` - version bump +## `Cargo.toml` - version bump Change the version of `cortex-m-rtic` to `"0.6.0"`. -### Module instead of Const +## Module instead of Const With the support of attributes on modules the `const APP` workaround is not needed. @@ -32,7 +32,7 @@ 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 +## Init always returns late resources In order to make the API more symmetric the #[init]-task always returns a late resource. @@ -64,7 +64,7 @@ mod app { } ``` -### Resources struct - #[resources] +## Resources struct - #[resources] Previously the RTIC resources had to be in in a struct named exactly "Resources":