From 007665eeee37cb9ef6f6bd9ef9a477fbf83fd520 Mon Sep 17 00:00:00 2001 From: CuriouslyCurious Date: Wed, 28 Jul 2021 13:55:12 +0200 Subject: [PATCH 1/5] book: Add note to remember to choose target --- book/en/src/by-example/app.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md index 50f2842cac..d23c2619aa 100644 --- a/book/en/src/by-example/app.md +++ b/book/en/src/by-example/app.md @@ -53,6 +53,10 @@ $ cargo run --example init {{#include ../../../../ci/expected/init.run}} ``` +> **NOTE**: Remember to always specify your chosen target device or configure +> one to be used by default in `.cargo/config.toml`. In this case, we use +> a Cortex M3 running in QEMU so the target is `thumbv7m-none-eabi`. + ## `idle` A function marked with the `idle` attribute can optionally appear in the @@ -120,7 +124,7 @@ crate. When the `priority` argument is omitted, the priority is assumed to be `1`. The `idle` task has a non-configurable static priority of `0`, the lowest priority. > A higher number means a higher priority in RTIC, which is the opposite from what -> Cortex-M does in the NVIC peripheral. +> Cortex-M does in the NVIC peripheral. > Explicitly, this means that number `10` has a **higher** priority than number `9`. When several tasks are ready to be executed the one with highest static From e90e6332f69cde78c902ba554b3d2930ab173124 Mon Sep 17 00:00:00 2001 From: CuriouslyCurious Date: Thu, 29 Jul 2021 00:29:34 +0200 Subject: [PATCH 2/5] book: Clarify target notice --- book/en/src/by-example/app.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md index d23c2619aa..e8e1d7a62e 100644 --- a/book/en/src/by-example/app.md +++ b/book/en/src/by-example/app.md @@ -53,9 +53,10 @@ $ cargo run --example init {{#include ../../../../ci/expected/init.run}} ``` -> **NOTE**: Remember to always specify your chosen target device or configure -> one to be used by default in `.cargo/config.toml`. In this case, we use -> a Cortex M3 running in QEMU so the target is `thumbv7m-none-eabi`. +> **NOTE**: Remember to specify your chosen target device by passing a target +> triple to cargo (e.g `cargo run --example init --target thumbv7m-none-eabi`) or +> configure a device to be used by default when building the examples in `.cargo/config.toml`. +> In this case, we use a Cortex M3 emulated in QEMU so the target is `thumbv7m-none-eabi`. ## `idle` From 7a977f3fa99adcdf160761bf96268e6c89dd27fb Mon Sep 17 00:00:00 2001 From: CuriouslyCurious Date: Thu, 29 Jul 2021 13:58:21 +0200 Subject: [PATCH 3/5] book: Add link to new.md --- book/en/src/by-example/app.md | 27 +-------------------------- 1 file changed, 1 insertion(+), 26 deletions(-) diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md index e8e1d7a62e..c84f7a41c9 100644 --- a/book/en/src/by-example/app.md +++ b/book/en/src/by-example/app.md @@ -6,32 +6,6 @@ This is the smallest possible RTIC application: {{#include ../../../../examples/smallest.rs}} ``` -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 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 -[`cortex_m_rt::entry`]: ../../../api/cortex_m_rt_macros/attr.entry.html - -## `init` - -Within the `app` module the attribute expects to find an initialization -function marked with the `init` attribute. This function must have -signature `fn(init::Context) -> (init::LateResources, init::Monotonics)`. - -This initialization function will be the first part of the application to run. -The `init` function will run *with interrupts disabled* and has exclusive access -to Cortex-M where the `bare_metal::CriticalSection` token is available as `cs`. -And optionally, device specific peripherals through the `core` and `device` fields -of `init::Context`. - `static mut` variables declared at the beginning of `init` will be transformed into `&'static mut` references that are safe to access. Notice, this feature may be deprecated in next release, see `task_local` resources. @@ -57,6 +31,7 @@ $ cargo run --example init > triple to cargo (e.g `cargo run --example init --target thumbv7m-none-eabi`) or > configure a device to be used by default when building the examples in `.cargo/config.toml`. > In this case, we use a Cortex M3 emulated in QEMU so the target is `thumbv7m-none-eabi`. +> See [`Starting a new project`](./new.md) for more info. ## `idle` From ae7b444f3d7e4a41f45aea47be3f14180028f36b Mon Sep 17 00:00:00 2001 From: CuriouslyCurious Date: Fri, 30 Jul 2021 12:43:35 +0200 Subject: [PATCH 4/5] Revert "book: Add link to new.md" This reverts commit 7a977f3fa99adcdf160761bf96268e6c89dd27fb. --- book/en/src/by-example/app.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md index c84f7a41c9..e8e1d7a62e 100644 --- a/book/en/src/by-example/app.md +++ b/book/en/src/by-example/app.md @@ -6,6 +6,32 @@ This is the smallest possible RTIC application: {{#include ../../../../examples/smallest.rs}} ``` +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 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 +[`cortex_m_rt::entry`]: ../../../api/cortex_m_rt_macros/attr.entry.html + +## `init` + +Within the `app` module the attribute expects to find an initialization +function marked with the `init` attribute. This function must have +signature `fn(init::Context) -> (init::LateResources, init::Monotonics)`. + +This initialization function will be the first part of the application to run. +The `init` function will run *with interrupts disabled* and has exclusive access +to Cortex-M where the `bare_metal::CriticalSection` token is available as `cs`. +And optionally, device specific peripherals through the `core` and `device` fields +of `init::Context`. + `static mut` variables declared at the beginning of `init` will be transformed into `&'static mut` references that are safe to access. Notice, this feature may be deprecated in next release, see `task_local` resources. @@ -31,7 +57,6 @@ $ cargo run --example init > triple to cargo (e.g `cargo run --example init --target thumbv7m-none-eabi`) or > configure a device to be used by default when building the examples in `.cargo/config.toml`. > In this case, we use a Cortex M3 emulated in QEMU so the target is `thumbv7m-none-eabi`. -> See [`Starting a new project`](./new.md) for more info. ## `idle` From f6f61f95a69786458a4fd06aa7fa33256b9e4603 Mon Sep 17 00:00:00 2001 From: CuriouslyCurious Date: Fri, 30 Jul 2021 12:44:35 +0200 Subject: [PATCH 5/5] book: Properly update the note with a link --- book/en/src/by-example/app.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md index e8e1d7a62e..5fd1c25051 100644 --- a/book/en/src/by-example/app.md +++ b/book/en/src/by-example/app.md @@ -57,6 +57,7 @@ $ cargo run --example init > triple to cargo (e.g `cargo run --example init --target thumbv7m-none-eabi`) or > configure a device to be used by default when building the examples in `.cargo/config.toml`. > In this case, we use a Cortex M3 emulated in QEMU so the target is `thumbv7m-none-eabi`. +> See [`Starting a new project`](./new.md) for more info. ## `idle`